Skip to content

Self-improving AI Employees for everyone

32.8 KB
Raw Blame
"""Edge-walking utilities for agent plugins.

Pure functions extracted from ``services/handlers/ai.py`` so every
agent plugin can call them without depending on the legacy handler
module. Used by :class:`AIAgentNode`, :class:`ChatAgentNode`,
:class:`SpecializedAgentBase`, :class:`RLMAgentNode`,
:class:`ClaudeCodeAgentNode`.

Three helpers:

- :func:`collect_agent_connections` — walks ``input-context``,
  ``input-skill``, ``input-tools``, ``input-main`` / ``input-chat``,
  ``input-task`` edges into a single tuple. Knows about the
  ``masterSkill`` expansion + direct Android service tools +
  child-agent tool discovery.
- :func:`collect_teammate_connections` — walks ``input-teammates``
  edges (orchestrator / ai_employee team-lead pattern).
- :func:`format_task_context` — renders ``taskTrigger`` payload as a
  prompt prepend block.

Wave 11.I, X3: the Master-Skill expansion logic moved out of this
module (it used to ``from services.skill_loader import get_skill_loader``
inline). The :mod:`nodes.skill` package registers an expander callback
via :func:`register_master_skill_expander` from its ``__init__.py``;
edge_walker calls the registered callback instead of importing
``skill_loader`` directly.

These functions have **no service dependencies** beyond the
``Database`` instance and the registered expander callback. They
mutate nothing. Wave 11.D.6 inlines the old ``handlers/ai.py:_collect_*``
shims to call here directly.
"""

from __future__ import annotations

import hashlib
import re
from collections import Counter
from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict, List, Optional, Tuple

from services.workspace_capabilities import is_registered_agent
from core.logging import get_logger

if TYPE_CHECKING:
    from core.database import Database

logger = get_logger(__name__)

TEAM_LEAD_TYPES = frozenset({"orchestrator_agent", "ai_employee"})
TEAMMATE_HANDLE = "input-teammates"


def edge_target_handle(edge: Dict[str, Any]) -> Optional[str]:
    """Return the canonical ReactFlow handle, accepting legacy imports."""
    return edge.get("targetHandle") or edge.get("target_handle")


def _delegate_slug(value: Any) -> str:
    slug = re.sub(r"[^a-zA-Z0-9]+", "_", str(value or "").strip()).strip("_").lower()
    return slug or "ai_agent"


def build_teammate_descriptors(node_id: str, context: Dict[str, Any]) -> List[Dict[str, Any]]:
    """Build deterministic, LLM-visible identities for a lead's teammates.

    Specialized agents retain their stable type-derived name. Custom
    ``aiAgent`` nodes are label-addressable and receive a node-id suffix when
    their label is empty or collides on the same lead surface.
    """
    nodes = context.get("nodes", []) or []
    edges = context.get("edges", []) or []
    node_by_id = {n.get("id"): n for n in nodes if n.get("id")}
    candidates: List[Dict[str, Any]] = []
    for edge in edges:
        if edge.get("target") != node_id or edge_target_handle(edge) != TEAMMATE_HANDLE:
            continue
        source = node_by_id.get(edge.get("source"))
        if not source or not is_registered_agent(source.get("type")):
            continue
        node_type = source.get("type", "")
        raw_label = (source.get("data") or {}).get("label")
        label = str(raw_label or node_type)
        candidates.append({
            "node_id": source["id"],
            "node_type": node_type,
            "label": label,
            "_raw_label": raw_label,
            "_slug": _delegate_slug(raw_label),
        })

    custom_counts = Counter(c["_slug"] for c in candidates if c["node_type"] == "aiAgent" and c["_raw_label"])
    for item in candidates:
        if item["node_type"] == "aiAgent":
            needs_suffix = not item["_raw_label"] or custom_counts[item["_slug"]] > 1
            stable_id = hashlib.sha1(str(item["node_id"]).encode("utf-8")).hexdigest()[:8]
            suffix = f"_{stable_id}" if needs_suffix else ""
            item["delegate_tool_name"] = f"delegate_to_{item['_slug']}{suffix}"
        else:
            item["delegate_tool_name"] = f"delegate_to_{item['node_type']}"
        item.pop("_raw_label", None)
        item.pop("_slug", None)
    return candidates


# ---- Master-Skill expander callback registry ----------------------------

MasterSkillExpander = Callable[
    [str, Dict[str, Any]],
    Awaitable[List[Dict[str, Any]]],
]
"""Async callable that expands a Master Skill node's ``skills_config``
into a list of per-skill entries (the same shape ``_append_skill_entries``
produces for non-master skills). Signature:
``(source_node_id, skills_config) -> list[entry]``."""

_MASTER_SKILL_EXPANDER: Optional[MasterSkillExpander] = None


def register_master_skill_expander(fn: MasterSkillExpander) -> None:
    """Publish the Master-Skill expander callback.

    Idempotent on equality. The :mod:`nodes.skill` plugin package
    registers its expander from ``__init__.py`` on package import.
    Edge-walking code calls :func:`get_master_skill_expander` and runs
    whatever's registered; the framework has no skill_loader coupling.
    """
    global _MASTER_SKILL_EXPANDER
    if _MASTER_SKILL_EXPANDER is not None and _MASTER_SKILL_EXPANDER != fn:
        raise ValueError("register_master_skill_expander: callback already registered " "by a different callable; refusing to overwrite")
    _MASTER_SKILL_EXPANDER = fn


# ---- Agent-Context descriptor builder registry ---------------------------

AgentContextBuilder = Callable[
    [str, Dict[str, Any], Any],
    Awaitable[Optional[Dict[str, Any]]],
]
"""Async callable that turns a Context node connected on ``input-context``
into the descriptor the agent runtime consumes. Signature:
``(source_node_id, context, database) -> descriptor | None``.

Returning ``None`` means "this connection contributes no context" and the
edge is skipped. The framework does not know the descriptor's shape — the
plugin that owns the node owns its keys."""

_AGENT_CONTEXT_BUILDER: Optional[AgentContextBuilder] = None


def register_agent_context_builder(fn: AgentContextBuilder) -> None:
    """Publish the Context descriptor builder.

    Idempotent on equality. ``nodes.context`` registers its builder from
    ``__init__.py`` on package import. Edge-walking code calls
    :func:`get_agent_context_builder` and runs whatever is registered, so
    the framework carries no knowledge of the Context node's parameters,
    thread-selection rules, or descriptor keys.
    """
    global _AGENT_CONTEXT_BUILDER
    if _AGENT_CONTEXT_BUILDER is not None and _AGENT_CONTEXT_BUILDER != fn:
        raise ValueError(
            "register_agent_context_builder: callback already registered "
            "by a different callable; refusing to overwrite"
        )
    _AGENT_CONTEXT_BUILDER = fn


def get_agent_context_builder() -> Optional[AgentContextBuilder]:
    """Return the registered Context builder, or None when no plugin has
    wired one (in which case ``input-context`` edges contribute nothing)."""
    return _AGENT_CONTEXT_BUILDER


def get_master_skill_expander() -> Optional[MasterSkillExpander]:
    """Return the registered expander callback, or None when no skill
    plugin has wired it (in which case Master-Skill nodes silently
    expand to no entries -- the agent still runs without skills)."""
    return _MASTER_SKILL_EXPANDER


async def collect_agent_connections(
    node_id: str,
    context: Dict[str, Any],
    database: "Database",
    log_prefix: str = "[Agent]",
) -> Tuple[
    Optional[Dict[str, Any]],  # context_data (legacy memory_data on V1)
    List[Dict[str, Any]],  # skill_data
    List[Dict[str, Any]],  # tool_data
    Optional[Dict[str, Any]],  # input_data
    Optional[Dict[str, Any]],  # task_data
]:
    """Walk edges targeting ``node_id`` and collect everything an agent
    needs from its connected nodes.

    Returns ``(context, skills, tools, input, task)``. The first item is an
    Agent Context reference/policy descriptor; legacy ``input-memory``
    graphs may still yield their recorded Memory descriptor.
    docstring for behaviour notes.
    """
    if context.get("parameter_snapshot"):
        from services.agent_bindings import ParameterSnapshotDatabase
        database = ParameterSnapshotDatabase(database, context["parameter_snapshot"])
    nodes = context.get("nodes")
    edges = context.get("edges")
    workflow_id = context.get("workflow_id")

    context_data: Optional[Dict[str, Any]] = None
    skill_data: List[Dict[str, Any]] = []
    tool_data: List[Dict[str, Any]] = []
    input_data: Optional[Dict[str, Any]] = None
    task_data: Optional[Dict[str, Any]] = None

    logger.info(
        f"{log_prefix} Processing node {node_id}, "
        f"edges={len(edges) if edges else 0}, "
        f"nodes={len(nodes) if nodes else 0}, "
        f"workflow_id={workflow_id}"
    )

    if not edges or not nodes:
        return context_data, skill_data, tool_data, input_data, task_data

    incoming_edges = [e for e in edges if e.get("target") == node_id]
    logger.info(f"{log_prefix} Incoming edges to {node_id}: {len(incoming_edges)}")
    if not incoming_edges:
        edge_targets = set(e.get("target") for e in edges)
        logger.debug(f"{log_prefix} All edge targets in graph: {edge_targets}")
    for e in incoming_edges:
        logger.debug(f"{log_prefix} Edge: source={e.get('source')}, " f"targetHandle={e.get('targetHandle')}")

    tool_incoming = [e for e in incoming_edges if edge_target_handle(e) == "input-tools"]
    logger.info(f"{log_prefix} Tool edges (input-tools handle): {len(tool_incoming)}")

    for edge in edges:
        if edge.get("target") != node_id:
            continue

        target_handle = edge_target_handle(edge)
        source_node_id = edge.get("source")
        source_node = next((n for n in nodes if n.get("id") == source_node_id), None)
        if not source_node:
            continue

        if target_handle == "input-context":
            # The descriptor's shape belongs to the plugin that owns the
            # node, not to the framework. Whatever is registered decides
            # whether this edge contributes context at all.
            builder = get_agent_context_builder()
            if builder is not None:
                built = await builder(
                    str(source_node_id or ""),
                    {**context, "workflow_id": str(workflow_id or "")},
                    database,
                )
                if built:
                    context_data = built
        elif target_handle == "input-memory":
            # Legacy input-memory graphs retain their recorded behavior.
            if source_node.get("type") == "simpleMemory":
                context_data = await _build_memory_entry(
                    node_id,
                    source_node_id,
                    database,
                    log_prefix,
                )

        elif target_handle == "input-skill":
            await _append_skill_entries(
                source_node,
                source_node_id,
                database,
                skill_data,
                log_prefix,
            )

        elif target_handle == "input-tools":
            await _append_tool_entry(
                source_node,
                source_node_id,
                edges,
                nodes,
                database,
                tool_data,
                log_prefix,
            )

        elif target_handle in ("input-main", "input-chat") or target_handle is None:
            source_output = context.get("outputs", {}).get(source_node_id)
            if source_output:
                input_data = source_output
                logger.debug(
                    f"{log_prefix} Input from {source_node.get('type')}: "
                    f"{list(source_output.keys()) if isinstance(source_output, dict) else type(source_output)}"
                )

        elif target_handle == "input-task":
            task_data = await _resolve_task_payload(
                source_node_id,
                source_node,
                context,
                log_prefix,
            )

    # A team lead must always be able to manage the durable work it delegates.
    # This is an intrinsic, non-removable team-lead capability.  It is present
    # before the first teammate is connected so the lead and its human panel
    # have one stable control surface for the whole execution lifecycle.
    current_node = next(
        (node for node in (context.get("nodes") or []) if node.get("id") == node_id),
        None,
    )
    # An employee's Talk contact submits jobs to its team. Prepare resolved the
    # plan from the generation's admitted graph: a Talk run never holds the lead
    # that carries it.
    plan = context.get("employee_team_plan") or {}
    if node_id == plan.get("talk_node_id") and not any(entry.get("node_type") == "taskManager" for entry in tool_data):
        tool_data.append({"node_id": f"builtin_task_manager_{node_id}", "node_type": "taskManager", "parameters": {}, "label": "Task Manager", "builtin": True})
    if (current_node or {}).get("type") in TEAM_LEAD_TYPES and not any(
        entry.get("node_type") == "taskManager" for entry in tool_data
    ):
        tool_data.append(
            {
                "node_id": f"builtin_task_manager_{node_id}",
                "node_type": "taskManager",
                "parameters": {},
                "label": "Task Manager",
                "builtin": True,
            }
        )
        logger.info("%s Auto-bound durable Task Manager for team lead %s", log_prefix, node_id)

    await bind_employee_job_source(node_id, context, database, tool_data)

    logger.info(
        f"{log_prefix} Collected: {len(skill_data)} skills, {len(tool_data)} tools, "
        f"context={'yes' if context_data else 'no'}, "
        f"input={'yes' if input_data else 'no'}, "
        f"task={'yes' if task_data else 'no'}"
    )
    for sd in skill_data:
        logger.debug(f"{log_prefix} Skill: type={sd.get('node_type')}, label={sd.get('label')}")
    for td in tool_data:
        logger.info(f"{log_prefix} Tool: type={td.get('node_type')}, node_id={td.get('node_id')}")

    return context_data, skill_data, tool_data, input_data, task_data


async def bind_employee_job_source(node_id, context, database, tool_data):
    """Add the intrinsic capability only after validating the actual caller."""
    if not context.get("employee_job_id") or any(entry.get("node_type") == "employeeJobSource" for entry in tool_data):
        return
    from services.employees.job_source import authorize_employee_job_source
    await authorize_employee_job_source(database, {**context, "parent_node_id": node_id})
    tool_data.append({"node_id": f"builtin_employee_job_source_{node_id}",
        "node_type": "employeeJobSource", "parameters": {},
        "label": "Employee Job Source", "builtin": True})


async def _build_memory_entry(
    agent_node_id: str,
    memory_node_id: str,
    database: "Database",
    log_prefix: str,
) -> Dict[str, Any]:
    memory_params = await database.get_node_parameters(memory_node_id) or {}
    # Plugin Pydantic models emit JSON Schema property names in
    # snake_case (post-Wave-11; see simple_memory.py "now that aliases
    # are gone"). Reads canonicalize on snake_case -- the saved-params
    # dict is the schema's domain.
    configured_session = memory_params.get("session_id", "")
    if configured_session and configured_session != "default":
        session_id = configured_session
    else:
        session_id = agent_node_id
    embedding_provider = str(
        memory_params.get("embedding_provider") or "huggingface"
    ).strip().lower()
    embedding_model = str(
        memory_params.get("embedding_model") or {
            "huggingface": "BAAI/bge-small-en-v1.5",
            "openai": "text-embedding-3-small",
            "ollama": "nomic-embed-text",
        }.get(embedding_provider, "")
    ).strip()
    entry = {
        "node_id": memory_node_id,
        "session_id": session_id,
        "window_size": int(memory_params.get("window_size", 10)),
        "memory_content": memory_params.get(
            "memory_content",
            "# Conversation History\n\n*No messages yet.*\n",
        ),
        "long_term_enabled": memory_params.get("long_term_enabled", False),
        "retrieval_count": int(memory_params.get("retrieval_count", 3)),
        "embedding_provider": embedding_provider,
        "embedding_model": embedding_model,
        "embedding_endpoint": str(
            memory_params.get("embedding_endpoint") or ""
        ).strip(),
        # Claude Code CLI session continuity: the UUID claude returned on
        # the previous successful run. claude_code_agent passes this as
        # `--resume <UUID>` so claude finds its own JSONL transcript at
        # `<CLAUDE_CONFIG_DIR>/projects/<cwd-encoded>/<UUID>.jsonl`.
        "last_session_id": memory_params.get("last_session_id"),
    }
    logger.info(
        "%s Connected memory node: node=%s session=%s (auto=%s) " "content_length=%d last_session_id=%s",
        log_prefix,
        memory_node_id,
        session_id,
        not configured_session or configured_session == "default",
        len(entry["memory_content"]),
        entry["last_session_id"],
    )
    return entry


async def _append_skill_entries(
    source_node: Dict[str, Any],
    source_node_id: str,
    database: "Database",
    skill_data: List[Dict[str, Any]],
    log_prefix: str,
) -> None:
    skill_type = source_node.get("type")
    skill_params = await database.get_node_parameters(source_node_id) or {}

    if skill_type == "masterSkill":
        expander = get_master_skill_expander()
        if expander is None:
            logger.warning(
                f"{log_prefix} Master Skill node found but no expander "
                "registered. Skipping expansion -- ensure nodes.skill "
                "is on the import path."
            )
            return

        skills_config = dict(skill_params.get("skills_config", {}))
        # The Assistant Master Skill owns the provider-neutral Skill tool's
        # usage contract. Keep this real, editable skill enabled for legacy
        # nodes whose saved params predate the default.
        if (skill_params.get("skill_folder") or "assistant") == "assistant":
            configured = dict(skills_config.get("skill") or {})
            configured.update({"enabled": True, "required": True})
            skills_config["skill"] = configured
        logger.debug(f"{log_prefix} Master Skill found with {len(skills_config)} configured skills")
        entries = await expander(source_node_id, skills_config)
        from services.agent_runtime_policy import runtime_behavior_version
        if runtime_behavior_version(skill_params):
            entries = [{**entry, "parameters": {**(entry.get("parameters") or {}), "runtime_behavior_version": 1}}
                       for entry in entries]
        skill_data.extend(entries)
        for entry in entries:
            logger.debug(f"{log_prefix} Master Skill enabled: {entry['skill_name']}")
    else:
        skill_data.append(
            {
                "node_id": source_node_id,
                "node_type": skill_type,
                "skill_name": skill_params.get("skill_name", skill_type),
                "parameters": skill_params,
                "label": source_node.get("data", {}).get("label", skill_type),
            }
        )
        logger.debug(f"{log_prefix} Connected skill: {skill_type}")


async def _append_tool_entry(
    source_node: Dict[str, Any],
    source_node_id: str,
    edges: List[Dict[str, Any]],
    nodes: List[Dict[str, Any]],
    database: "Database",
    tool_data: List[Dict[str, Any]],
    log_prefix: str,
) -> None:
    tool_type = source_node.get("type")
    logger.info(f"{log_prefix} Found tool connected via input-tools: type={tool_type}, node_id={source_node_id}")
    tool_params = await database.get_node_parameters(source_node_id) or {}

    tool_entry: Dict[str, Any] = {
        "node_id": source_node_id,
        "node_type": tool_type,
        "parameters": tool_params,
        "label": source_node.get("data", {}).get("label", tool_type),
    }

    if is_registered_agent(tool_type):
        child_tools: List[Dict[str, Any]] = []
        child_incoming_edges = [e for e in edges if e.get("target") == source_node_id]
        child_tool_edges = [e for e in child_incoming_edges if edge_target_handle(e) == "input-tools"]
        logger.debug(
            f"{log_prefix} Child agent {source_node_id}: "
            f"{len(child_incoming_edges)} incoming edges, "
            f"{len(child_tool_edges)} input-tools edges"
        )
        if child_incoming_edges:
            handles = [e.get("targetHandle", "None") for e in child_incoming_edges]
            logger.debug(f"{log_prefix} Child agent {source_node_id} incoming handles: {handles}")
        for child_edge in edges:
            if child_edge.get("target") != source_node_id:
                continue
            if edge_target_handle(child_edge) != "input-tools":
                continue
            child_tool_id = child_edge.get("source")
            child_tool_node = next((n for n in nodes if n.get("id") == child_tool_id), None)
            logger.debug(
                f"{log_prefix} Child agent {source_node_id}: " f"tool edge from {child_tool_id}, node found: {child_tool_node is not None}"
            )
            if child_tool_node:
                child_tool_type = child_tool_node.get("type", "")
                child_tool_label = child_tool_node.get("data", {}).get("label", child_tool_type)
                child_tools.append({"node_type": child_tool_type, "label": child_tool_label})
        if child_tools:
            tool_entry["child_tools"] = child_tools
            logger.debug(f"{log_prefix} Child agent {source_node_id} has tools: " f"{[t['label'] for t in child_tools]}")

    tool_data.append(tool_entry)
    logger.debug(f"{log_prefix} Connected tool: {tool_type}")


async def _resolve_task_payload(
    source_node_id: str,
    source_node: Dict[str, Any],
    context: Dict[str, Any],
    log_prefix: str,
) -> Optional[Dict[str, Any]]:
    logger.info(f"{log_prefix} Found input-task edge from {source_node_id} (type={source_node.get('type')})")

    source_output = context.get("outputs", {}).get(source_node_id)
    logger.info(f"{log_prefix} Context outputs check for {source_node_id}: {source_output is not None}")

    if not source_output:
        get_output_fn = context.get("get_output_fn")
        session_id = context.get("session_id", "default")
        if get_output_fn:
            try:
                source_output = await get_output_fn(session_id, source_node_id, "output_0")
                logger.info(f"{log_prefix} DB lookup for {source_node_id}: {source_output is not None}")
            except Exception as e:
                logger.warning(f"{log_prefix} Failed to get output from DB: {e}")
        else:
            logger.warning(f"{log_prefix} No get_output_fn in context, cannot retrieve task output")

    logger.info(
        f"{log_prefix} Source output for {source_node_id}: {source_output is not None}, "
        f"type={type(source_output).__name__ if source_output else 'None'}"
    )
    if not source_output:
        return None

    task_data = extract_task_event_payload(source_output) or source_output
    if isinstance(task_data, dict):
        logger.info(
            f"{log_prefix} Task completion data: task_id={task_data.get('task_id')}, "
            f"status={task_data.get('status')}, agent_name={task_data.get('agent_name')}"
        )
    return task_data


def extract_task_event_payload(value: Any) -> Optional[Dict[str, Any]]:
    """Unwrap task data from executor and CloudEvent envelopes."""
    current = value
    seen: set[int] = set()
    while isinstance(current, dict) and id(current) not in seen:
        seen.add(id(current))
        if current.get("task_id") and current.get("status"):
            return current
        nested = current.get("data")
        if not isinstance(nested, dict):
            nested = current.get("result")
        if not isinstance(nested, dict):
            return None
        current = nested
    return None


# Cap on each tool / skill blurb inside a teammate's capability summary.
# The summary rides the lead's system prompt once per teammate, so it must
# stay a roster line, not a manual: full instructions live on the teammate.
_CAPABILITY_BLURB_CHARS = 160
# Master-Skill entries that describe the agent runtime rather than a domain
# capability. They are enabled on every Master Skill node and would only add
# noise to a roster.
_ROSTER_SKIPPED_SKILLS = frozenset({"skill"})


def _clip(text: str, limit: int = _CAPABILITY_BLURB_CHARS) -> str:
    text = " ".join(str(text or "").split())
    return text if len(text) <= limit else text[: limit - 3].rstrip() + "..."


def _tool_blurb(node_type: str) -> str:
    """One-line, human-facing capability text for a tool node type.

    Prefers the plugin's ``description`` ClassVar (a sentence written for
    people) over ``tool_description`` (an instruction block written for the
    model that holds the tool) so a lead's roster stays readable.
    """
    from services.node_registry import get_node_class

    cls = get_node_class(node_type)
    if cls is None:
        return ""
    return _clip(
        (getattr(cls, "description", "") or "").strip()
        or (getattr(cls, "tool_description", "") or "").strip()
    )


async def _teammate_child_skills(
    teammate_id: str,
    nodes: List[Dict[str, Any]],
    edges: List[Dict[str, Any]],
    database: "Database",
) -> List[Dict[str, Any]]:
    """Skills wired to a teammate's ``input-skill`` handle, with descriptions.

    Master Skill nodes expand to their enabled entries; the description is
    the SKILL.md frontmatter text (or the per-node override), the same value
    the teammate's own ``Skill`` catalogue shows. Personality and runtime
    skills are skipped: they shape how the agent behaves, not what it can
    do for the lead.
    """
    skills: List[Dict[str, Any]] = []
    registry = None
    for edge in edges:
        if edge.get("target") != teammate_id or edge_target_handle(edge) != "input-skill":
            continue
        child = next((n for n in nodes if n.get("id") == edge.get("source")), None)
        if not child:
            continue
        params = await database.get_node_parameters(child.get("id")) or {}
        if child.get("type") == "masterSkill":
            skills_config = params.get("skills_config") or {}
            if not isinstance(skills_config, dict):
                continue
            for skill_key, skill_cfg in skills_config.items():
                if not isinstance(skill_cfg, dict) or not skill_cfg.get("enabled", False):
                    continue
                if skill_key in _ROSTER_SKIPPED_SKILLS or skill_key.endswith("-personality"):
                    continue
                if registry is None:
                    from services.skill_loader import get_skill_loader

                    try:
                        registry = get_skill_loader().scan_skills()
                    except Exception as exc:  # noqa: BLE001 - a roster must never fail a run
                        logger.warning("[Teams] skill registry unavailable for roster: %s", exc)
                        registry = {}
                meta = registry.get(skill_key)
                description = skill_cfg.get("description") or (meta.description if meta else "")
                skills.append({"node_id": child.get("id"), "skill_name": skill_key, "description": _clip(description)})
        else:
            skill_name = params.get("skill_name") or (child.get("data") or {}).get("label") or child.get("type")
            skills.append({"node_id": child.get("id"), "skill_name": str(skill_name), "description": ""})
    return skills


def describe_teammate_capabilities(
    child_tools: List[Dict[str, Any]],
    child_skills: List[Dict[str, Any]],
) -> str:
    """Render a teammate's connected tools and skills as one roster sentence.

    ``"tools: TikHub (Scrape TikTok, Douyin, ...); skills: tikhub-skill
    (...)"``. Empty when the teammate has neither, so callers can omit the
    clause entirely.
    """
    parts: List[str] = []
    tool_bits = []
    for tool in child_tools:
        label = str(tool.get("label") or tool.get("node_type") or "")
        blurb = _tool_blurb(str(tool.get("node_type") or ""))
        tool_bits.append(f"{label} ({blurb})" if blurb else label)
    if tool_bits:
        parts.append("tools: " + ", ".join(tool_bits))
    skill_bits = []
    for skill in child_skills:
        name = str(skill.get("skill_name") or "")
        blurb = str(skill.get("description") or "")
        skill_bits.append(f"{name} ({blurb})" if blurb else name)
    if skill_bits:
        parts.append("skills: " + ", ".join(skill_bits))
    return "; ".join(parts)


def format_teammate_roster_line(info: Dict[str, Any]) -> str:
    """The one line a lead sees per teammate, shared by both runtimes.

    ``- <node_id>: <label> (<node_type>) - <capabilities>``. The capability
    clause is what lets a lead match work to the agent holding the right
    tool; without it a teammate labelled "Web Agent" carrying TikHub is
    indistinguishable from one carrying nothing.
    """
    line = f"- {info.get('node_id')}: {info.get('label') or info.get('node_type')} ({info.get('node_type')})"
    capabilities = str(info.get("capabilities") or "").strip()
    return f"{line} - {capabilities}" if capabilities else line


async def collect_teammate_connections(
    node_id: str,
    context: Dict[str, Any],
    database: "Database",
) -> List[Dict[str, Any]]:
    """Walk ``input-teammates`` edges and return connected agents.

    Used by ``orchestrator_agent`` / ``ai_employee``. Each teammate carries
    its ``child_tools`` (``input-tools`` edges), ``child_skills``
    (``input-skill`` edges) and a rendered ``capabilities`` sentence: the
    text the lead's roster shows, since the delegate tools themselves are
    hidden from the lead's model.
    """
    if context.get("parameter_snapshot"):
        from services.agent_bindings import ParameterSnapshotDatabase
        database = ParameterSnapshotDatabase(database, context["parameter_snapshot"])
    teammates: List[Dict[str, Any]] = []
    descriptors = build_teammate_descriptors(node_id, context)
    nodes = context.get("nodes", []) or []
    edges = context.get("edges", []) or []
    for descriptor in descriptors:
        source_id = descriptor["node_id"]
        params = await database.get_node_parameters(source_id) or {}
        child_tools: List[Dict[str, Any]] = []
        for edge in edges:
            if edge.get("target") != source_id or edge_target_handle(edge) != "input-tools":
                continue
            child = next((n for n in nodes if n.get("id") == edge.get("source")), None)
            if child:
                child_tools.append({
                    "node_id": child.get("id"),
                    "node_type": child.get("type"),
                    "label": (child.get("data") or {}).get("label", child.get("type")),
                })
        child_skills = await _teammate_child_skills(source_id, nodes, edges, database)
        teammates.append({
            **descriptor,
            "parameters": params,
            "child_tools": child_tools,
            "child_skills": child_skills,
            "capabilities": describe_teammate_capabilities(child_tools, child_skills),
        })
        logger.debug(f"[Teams] Found teammate: {descriptor['node_type']} ({source_id})")

    return teammates


def format_task_context(task_data: Dict[str, Any]) -> str:
    """Render a ``taskTrigger`` payload as a prompt-prepend block.

    Tells the lead to review the delegated result and choose the next
    lifecycle action. Three branches: completed / error / other.
    """
    status = task_data.get("status", "unknown")
    agent_name = task_data.get("agent_name", "Unknown Agent")
    task_id = task_data.get("task_id", "")

    if status == "completed":
        result = task_data.get("result", "No result provided")
        return (
            "A delegated task has completed:\n"
            f"- Agent: {agent_name}\n"
            f"- Task ID: {task_id}\n"
            "- Status: Completed Successfully\n"
            f"- Result: {result}\n\n"
            "This taskTrigger run is the lead's completion review. Use Task Manager "
            "list_tasks and get_task to read the durable task, verify the submitted "
            "result against its mission and acceptance criteria, then produce the "
            "requested user-facing output. Do not create a duplicate assignment."
        )

    if status == "error":
        error = task_data.get("error", "Unknown error")
        return (
            "A delegated task has failed:\n"
            f"- Agent: {agent_name}\n"
            f"- Task ID: {task_id}\n"
            "- Status: Error\n"
            f"- Error: {error}\n\n"
            "This taskTrigger run is the lead's failure review. Use Task Manager "
            "list_tasks and get_task to inspect the durable attempt before reporting, "
            "retrying, or reassigning it. Do not create a duplicate assignment."
        )

    return f"Task update received:\n" f"- Agent: {agent_name}\n" f"- Task ID: {task_id}\n" f"- Status: {status}\n" f"- Data: {task_data}"