mas-lab-component-controller 0.2.0__py3-none-any.whl

mas/lab/controller/ui_stream/run_index.py

@@ -0,0 +1,337 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Resolve run artefacts from experiment/scenario/test/run (or session) ids."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from mas.lab.controller.ui_stream.refs import DataSourceRef
+
+
+@dataclass
+class RunRecord:
+    ref: DataSourceRef
+    events: Path | None = None
+    artefacts: dict[str, Path] = field(default_factory=dict)
+
+
+def _read_yaml(path: Path) -> dict[str, Any]:
+    import yaml
+
+    if not path.is_file():
+        return {}
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    return data if isinstance(data, dict) else {}
+
+
+def find_experiment_file(lib_dir: Path, experiment: str | None) -> Path | None:
+    if not experiment:
+        for name in ("experiment.yaml", "experiments/experiment.yaml"):
+            candidate = lib_dir / name
+            if candidate.is_file():
+                return candidate
+        return None
+    candidates = [
+        lib_dir / experiment,
+        lib_dir / "experiments" / experiment,
+    ]
+    if not experiment.endswith((".yaml", ".yml")):
+        candidates.extend(
+            [
+                lib_dir / f"{experiment}.yaml",
+                lib_dir / "experiments" / f"{experiment}.yaml",
+            ]
+        )
+    for path in candidates:
+        if path.is_file():
+            return path
+    extra = list(lib_dir.glob("*.yaml"))
+    experiments_dir = lib_dir / "experiments"
+    if experiments_dir.is_dir():
+        extra.extend(experiments_dir.glob("*.yaml"))
+    for path in extra:
+        doc = _read_yaml(path)
+        name = str((doc.get("experiment") or {}).get("name") or doc.get("name") or path.stem)
+        if name == experiment or path.stem == experiment:
+            return path
+    return None
+
+
+def _experiment_application(lib_dir: Path, experiment: str | None) -> dict[str, Any]:
+    path = find_experiment_file(lib_dir, experiment)
+    if path is None:
+        return {}
+    doc = _read_yaml(path)
+    exp = doc.get("experiment") if isinstance(doc.get("experiment"), dict) else doc
+    app = (exp or {}).get("application")
+    if isinstance(app, dict):
+        return app
+    apps = (exp or {}).get("applications") or []
+    if apps and isinstance(apps[0], dict):
+        return apps[0]
+    return {}
+
+
+def infer_mas_rel(lib_dir: Path, experiment: str | None) -> str | None:
+    binding = _experiment_application(lib_dir, experiment)
+    manifest = str(binding.get("manifest") or "").strip()
+    if manifest:
+        return manifest.lstrip("./")
+    for rel in ("mas/scenario-1.mas.yaml", "mas.yaml"):
+        if (lib_dir / rel).is_file():
+            return rel
+    return None
+
+
+def resolve_mas_files(lib_dir: Path, experiment: str | None) -> tuple[Path, Path] | None:
+    """Return ``(mas.yaml, MAS directory)`` for a catalog app or a relative manifest."""
+    binding = _experiment_application(lib_dir, experiment)
+    app_ref = str(binding.get("app") or "").strip()
+    if app_ref:
+        try:
+            from mas.apps import get_app, resolve_app_manifest
+
+            manifest = resolve_app_manifest(get_app(app_ref), app_id=app_ref)
+        except Exception:
+            return None
+        return manifest, manifest.parent
+    rel = infer_mas_rel(lib_dir, experiment)
+    if not rel:
+        return None
+    manifest = Path(rel) if Path(rel).is_absolute() else lib_dir / rel
+    if not manifest.is_file():
+        return None
+    return manifest, manifest.parent
+
+
+def overlay_rel(lib_dir: Path, overlay: str | None) -> Path | None:
+    if not overlay:
+        return None
+    name = overlay if overlay.endswith((".yaml", ".yml")) else f"{overlay}.yaml"
+    for folder in (lib_dir / "mas" / "overlays", lib_dir / "overlays", lib_dir / "mas" / "configs"):
+        candidate = folder / name
+        if candidate.is_file():
+            return candidate
+    skip = {".cache", "versions", "node_modules", ".git"}
+    matches = [path for path in lib_dir.rglob(name) if not skip.intersection(path.parts)]
+    return matches[0] if matches else None
+
+
+def _item_dir_name(test: str | None) -> str:
+    raw = str(test or "1").strip() or "1"
+    if raw.startswith("item"):
+        return raw
+    return f"item{raw}"
+
+
+def _run_dir_name(run: str | None) -> str:
+    raw = str(run or "1").strip() or "1"
+    if raw.startswith("r") and raw[1:].isdigit():
+        return raw
+    if raw.isdigit():
+        return f"r{raw}"
+    return raw
+
+
+def _is_run_index(run: str | None) -> bool:
+    raw = str(run or "").strip()
+    if not raw:
+        return False
+    if raw.isdigit():
+        return True
+    return raw.startswith("r") and raw[1:].isdigit()
+
+
+def _newest_scenario_run(
+    root: Path,
+    scenario: str,
+    item: str | None,
+    *,
+    glob_ok: bool,
+    experiment: str | None,
+) -> Path | None:
+    item_pat = item or "item*"
+    patterns = [f"{scenario}/{item_pat}/r*"]
+    if experiment:
+        patterns.append(f"{experiment}/{scenario}/{item_pat}/r*")
+    if glob_ok:
+        patterns.append(f"**/{scenario}/{item_pat}/r*")
+    found: list[Path] = []
+    for pattern in patterns:
+        for path in root.glob(pattern):
+            if path.is_dir() and path.name.startswith("r") and path.name[1:].isdigit():
+                found.append(path)
+    if not found:
+        return None
+    return max(found, key=lambda path: path.stat().st_mtime)
+
+
+def _standard_run_dir(lib_dir: Path, ref: DataSourceRef) -> Path | None:
+    scenario = ref.scenario
+    if not scenario:
+        return None
+    item = _item_dir_name(ref.test) if ref.test else None
+    run = _run_dir_name(ref.run) if _is_run_index(ref.run) else None
+    local_roots: list[Path] = []
+    for name in ("output", "outputs", "runs"):
+        candidate = lib_dir / name
+        if candidate.is_dir():
+            local_roots.append(candidate)
+    extra_roots: list[Path] = []
+    try:
+        from mas.lab.paths import data_dir, labs_root
+
+        extra_roots.append(data_dir())
+        extra_roots.append(labs_root())
+    except Exception:
+        pass
+
+    def _match(root: Path, *, glob_ok: bool) -> Path | None:
+        if run is not None:
+            item_name = item or _item_dir_name(None)
+            direct = root / scenario / item_name / run
+            if direct.is_dir():
+                return direct
+            if ref.experiment:
+                nested = root / ref.experiment / scenario / item_name / run
+                if nested.is_dir():
+                    return nested
+            if glob_ok:
+                matches = list(root.glob(f"**/{scenario}/{item_name}/{run}"))
+                if matches:
+                    return matches[0]
+            return None
+        if not glob_ok:
+            return None
+        return _newest_scenario_run(
+            root, scenario, item, glob_ok=True, experiment=ref.experiment
+        )
+
+    for root in local_roots:
+        found = _match(root, glob_ok=True)
+        if found is not None:
+            return found
+    for root in extra_roots:
+        found = _match(root, glob_ok=False)
+        if found is not None:
+            return found
+    return None
+
+
+def _events_in_run_dir(run_dir: Path) -> Path | None:
+    try:
+        from mas.lab.benchmark.cache.trace_store import resolve_run_events_path
+
+        found = resolve_run_events_path(run_dir)
+        if found is not None:
+            return found
+    except Exception:
+        pass
+    inline = run_dir / "traces" / "events.jsonl"
+    return inline if inline.is_file() else None
+
+
+def _gold_events(lib_dir: Path, scenario: str) -> Path | None:
+    cache = lib_dir / "infra" / ".cache"
+    if not cache.is_dir():
+        return None
+    exact = list(cache.glob(f"**/{scenario}.events.jsonl"))
+    if exact:
+        return sorted(exact)[-1]
+    return None
+
+
+def _gold_metrics(lib_dir: Path, scenario: str) -> Path | None:
+    cache = lib_dir / "infra" / ".cache"
+    if not cache.is_dir():
+        return None
+    exact = list(cache.glob(f"**/{scenario}.metrics.json"))
+    if exact:
+        return sorted(exact)[-1]
+    return None
+
+
+def _gold_progress(lib_dir: Path, scenario: str) -> Path | None:
+    cache = lib_dir / "infra" / ".cache"
+    if not cache.is_dir():
+        return None
+    exact = list(cache.glob(f"**/{scenario}.progress.jsonl"))
+    if exact:
+        return sorted(exact)[-1]
+    return None
+
+
+def _gold_custom_owners(lib_dir: Path, scenario: str) -> dict[str, Path]:
+    """Gold-cache siblings for every ``custom.{owner}`` trace actually present,
+    e.g. ``infra/.cache/{scenario}.custom.topology.jsonl``, next to the
+    existing ``{scenario}.events.jsonl`` / ``{scenario}.metrics.json``
+    convention. Discovered by glob, not a hardcoded owner list."""
+    cache = lib_dir / "infra" / ".cache"
+    if not cache.is_dir():
+        return {}
+    found: dict[str, Path] = {}
+    prefix, suffix = f"{scenario}.custom.", ".jsonl"
+    for path in cache.glob(f"**/{scenario}.custom.*.jsonl"):
+        owner = path.name[len(prefix) : -len(suffix)]
+        if owner and (owner not in found or path.stat().st_mtime > found[owner].stat().st_mtime):
+            found[owner] = path
+    return found
+
+
+def resolve_run(lib_dir: Path, ref: DataSourceRef, *, indexed: dict[str, RunRecord] | None = None) -> RunRecord:
+    if indexed:
+        for key in (ref.run or "", ref.session or "", ref.coordinate()):
+            if key and key in indexed:
+                return indexed[key]
+    run_dir = _standard_run_dir(lib_dir, ref)
+    events = _events_in_run_dir(run_dir) if run_dir else None
+    if events is None and ref.scenario:
+        events = _gold_events(lib_dir, ref.scenario)
+    artefacts: dict[str, Path] = {}
+    if events:
+        artefacts["events"] = events
+    if run_dir:
+        for key, name in (
+            ("metrics", "metrics.json"),
+            ("progress", "progress.jsonl"),
+            ("progress_latest", "progress.json"),
+            ("protocol", "protocol.json"),
+            ("report", "session_report.yaml"),
+            ("dataframe", "data.csv"),
+        ):
+            path = run_dir / name
+            if path.is_file():
+                artefacts[key] = path
+        if "report" not in artefacts:
+            json_report = run_dir / "session_report.json"
+            if json_report.is_file():
+                artefacts["report"] = json_report
+        # custom.{owner}.jsonl siblings (file_tail.append_custom_trace) --
+        # discovered by glob so any owner is picked up with no code change.
+        for path in run_dir.glob("custom.*.jsonl"):
+            owner = path.stem.split(".", 1)[1] if path.stem.count(".") >= 1 else ""
+            if owner:
+                artefacts[f"custom_{owner}"] = path
+    if "metrics" not in artefacts and events is not None:
+        sibling = events.with_name(events.name.replace(".events.jsonl", ".metrics.json"))
+        if sibling.is_file():
+            artefacts["metrics"] = sibling
+    if "progress" not in artefacts and events is not None:
+        sibling = events.with_name(events.name.replace(".events.jsonl", ".progress.jsonl"))
+        if sibling.is_file():
+            artefacts["progress"] = sibling
+    if "metrics" not in artefacts and ref.scenario:
+        gold = _gold_metrics(lib_dir, ref.scenario)
+        if gold is not None:
+            artefacts["metrics"] = gold
+    if "progress" not in artefacts and ref.scenario:
+        gold = _gold_progress(lib_dir, ref.scenario)
+        if gold is not None:
+            artefacts["progress"] = gold
+    if ref.scenario:
+        for owner, path in _gold_custom_owners(lib_dir, ref.scenario).items():
+            artefacts.setdefault(f"custom_{owner}", path)
+    return RunRecord(ref=ref, events=events, artefacts=artefacts)

mas/lab/controller/ui_stream/spec_load.py

@@ -0,0 +1,48 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Load a MAS topology snapshot from library files using catalog ids."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from mas.lab.controller.ui_stream.run_index import overlay_rel, resolve_mas_files
+from mas.lab.controller.ui_stream.spec_snapshot import load_yaml_text, snapshot_from_documents
+
+
+def _read_path(path: Path) -> dict[str, Any]:
+    if not path.is_file():
+        return {}
+    return load_yaml_text(path.read_text(encoding="utf-8"))
+
+
+def snapshot_for_ref(lib_dir: Path, *, experiment: str | None, overlay: str | None) -> dict[str, Any]:
+    files = resolve_mas_files(lib_dir, experiment)
+    if files is None:
+        raise FileNotFoundError("could not infer MAS spec from experiment id")
+    manifest, mas_dir = files
+    mas_doc = _read_path(manifest)
+    spec = mas_doc.get("spec") if isinstance(mas_doc.get("spec"), dict) else mas_doc
+    agency = (spec or {}).get("agency") or {}
+    agent_docs: dict[str, dict[str, Any]] = {}
+    for item in agency.get("agents") or []:
+        if isinstance(item, str):
+            aid = Path(item).stem
+            rel = item
+        elif isinstance(item, dict):
+            aid = str(item.get("id") or "").strip()
+            rel = str(item.get("ref") or "").strip()
+        else:
+            continue
+        if not aid:
+            continue
+        if rel:
+            agent_docs[aid] = _read_path(mas_dir / rel)
+        else:
+            agent_docs[aid] = {}
+    overlay_doc = None
+    overlay_path = overlay_rel(lib_dir, overlay)
+    if overlay_path is not None:
+        overlay_doc = load_yaml_text(overlay_path.read_text(encoding="utf-8"))
+    return snapshot_from_documents(mas_doc, agent_docs, overlay_doc)

mas/lab/controller/ui_stream/spec_snapshot.py

@@ -0,0 +1,313 @@
+#  Copyright (c) 2026 Cisco Systems, Inc. and its affiliates
+#  SPDX-License-Identifier: Apache-2.0
+"""Build a MAS topology snapshot for the demo-ui spec stream."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+from mas.runtime.boundary.delegation.policy import parse_delegate_tool_name
+
+
+def _as_list(value: Any) -> list[Any]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    return [value]
+
+
+def _skill_name(item: Any) -> str:
+    if isinstance(item, str):
+        return item.strip()
+    if isinstance(item, dict):
+        return str(item.get("name") or item.get("id") or item.get("ref") or "").strip()
+    return str(item or "").strip()
+
+
+def _tool_name(item: Any, mas_dir: Path | None = None) -> str:
+    if isinstance(item, str):
+        text = item.strip()
+        if text.endswith(".yaml") or text.endswith(".yml"):
+            return Path(text).stem
+        return text
+    if isinstance(item, dict):
+        named = str(item.get("name") or item.get("id") or "").strip()
+        if named:
+            return named
+        ref = str(item.get("ref") or "").strip()
+        if ref:
+            return Path(ref).stem
+    return ""
+
+
+def _agent_skills(doc: dict[str, Any]) -> list[str]:
+    spec = doc.get("spec") if isinstance(doc.get("spec"), dict) else doc
+    names: list[str] = []
+    for item in _as_list((spec or {}).get("skills")):
+        name = _skill_name(item)
+        if name:
+            names.append(name)
+    return names
+
+
+def _agent_tools(doc: dict[str, Any]) -> list[str]:
+    spec = doc.get("spec") if isinstance(doc.get("spec"), dict) else doc
+    names: list[str] = []
+    for item in _as_list((spec or {}).get("tools")):
+        name = _tool_name(item)
+        if name:
+            names.append(name)
+    return names
+
+
+def _overlay_skill_adds(overlay: dict[str, Any] | None) -> dict[str, list[str]]:
+    if not isinstance(overlay, dict):
+        return {}
+    patch = ((overlay.get("spec") or {}).get("patch") or {}).get("agents") or {}
+    if not isinstance(patch, dict):
+        return {}
+    out: dict[str, list[str]] = {}
+    for key, body in patch.items():
+        if not isinstance(body, dict):
+            continue
+        skills = body.get("skills") or {}
+        added = skills.get("$op", {}).get("add") if isinstance(skills, dict) else None
+        if added is None and isinstance(skills, dict):
+            added = skills.get("add")
+        names = [_skill_name(item) for item in _as_list(added)]
+        names = [name for name in names if name]
+        if names:
+            out[str(key)] = names
+    return out
+
+
+def apply_overlay_skills(
+    agents: list[dict[str, Any]],
+    overlay: dict[str, Any] | None,
+    entry_id: str,
+) -> None:
+    adds = _overlay_skill_adds(overlay)
+    if not adds:
+        return
+    by_id = {str(item["id"]): item for item in agents}
+    for key, names in adds.items():
+        targets: list[str]
+        if key in {"$all", "all"}:
+            targets = list(by_id)
+        elif key in {"$entry", "entry"}:
+            targets = [entry_id] if entry_id in by_id else []
+        elif key in {"$not-entry", "not-entry"}:
+            targets = [aid for aid in by_id if aid != entry_id]
+        else:
+            targets = [key] if key in by_id else []
+        for aid in targets:
+            have = list(by_id[aid].get("skills") or [])
+            for name in names:
+                if name not in have:
+                    have.append(name)
+            by_id[aid]["skills"] = have
+
+
+def snapshot_from_documents(
+    mas_doc: dict[str, Any],
+    agent_docs: dict[str, dict[str, Any]] | None = None,
+    overlay_doc: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Return a UI topology snapshot: entry, agents, tools, skills, workflow edges."""
+    spec = mas_doc.get("spec") if isinstance(mas_doc.get("spec"), dict) else mas_doc
+    agency = (spec or {}).get("agency") or {}
+    workflow = (spec or {}).get("workflow") or {}
+    entry = str(workflow.get("entry") or "").strip()
+    listed = _as_list(agency.get("agents"))
+    agent_docs = agent_docs or {}
+    agents: list[dict[str, Any]] = []
+    delegates: dict[str, list[str]] = {}
+    for item in listed:
+        if isinstance(item, str):
+            aid = item
+        elif isinstance(item, dict):
+            aid = str(item.get("id") or item.get("name") or "").strip()
+        else:
+            continue
+        if not aid:
+            continue
+        if not entry:
+            entry = aid
+        doc = agent_docs.get(aid) or {}
+        agents.append(
+            {
+                "id": aid,
+                "tools": _agent_tools(doc),
+                "skills": _agent_skills(doc),
+            }
+        )
+    for node in _as_list(workflow.get("nodes")):
+        if not isinstance(node, dict):
+            continue
+        nid = str(node.get("id") or "").strip()
+        peers = [str(p).strip() for p in _as_list(node.get("delegates_to")) if str(p).strip()]
+        if nid and peers:
+            delegates[nid] = peers
+    apply_overlay_skills(agents, overlay_doc, entry)
+    return {
+        "kind": "mas_topology",
+        "entry": entry,
+        "user": "user",
+        "agents": agents,
+        "delegates_to": delegates,
+    }
+
+
+_SKIP_ENTRY = frozenset({"", "mas", "user", "agent"})
+_HUB_HINTS = frozenset({"coordinator", "orchestrator", "planner"})
+_HUB_TOOLS = frozenset({"activate_skill", "run_action"})
+
+
+def infer_implicit_delegates(
+    agents: list[dict[str, Any]],
+    records: list[dict[str, Any]] | None = None,
+    hinted: str = "",
+) -> tuple[str, dict[str, list[str]]]:
+    """Star from the coordinator when the trace has no ``delegate_to_*`` tools."""
+    ids = [
+        str(agent.get("id") or "").strip()
+        for agent in agents
+        if isinstance(agent, dict) and str(agent.get("id") or "").strip() not in _SKIP_ENTRY
+    ]
+    ids = [aid for aid in ids if aid]
+    if len(ids) < 2:
+        return "", {}
+    hub = next((aid for aid in ids if aid.lower() in _HUB_HINTS), "")
+    last_speaker = ""
+    for record in records or []:
+        if not isinstance(record, dict):
+            continue
+        aid = str(record.get("agent_id") or "").strip()
+        if aid not in ids:
+            continue
+        kind = str(record.get("kind") or "")
+        tool = str(record.get("tool_name") or "")
+        if kind == "tool_call_start" and tool in _HUB_TOOLS:
+            hub = aid
+        if kind in {"user_response", "llm_call_end", "client_response"}:
+            last_speaker = aid
+    if not hub:
+        hinted = str(hinted or "").strip()
+        hub = hinted if hinted in ids else last_speaker or ids[0]
+    others = [aid for aid in ids if aid != hub]
+    return hub, ({hub: others} if hub and others else {})
+
+
+def pick_entry(
+    agents: list[dict[str, Any]],
+    delegates: dict[str, list[str]],
+    hinted: str = "",
+) -> str:
+    """Entry is the unique delegate hub, not the first native agent_id (often ``mas``)."""
+    children = {str(peer) for peers in (delegates or {}).values() for peer in (peers or [])}
+    roots = [
+        str(src)
+        for src in (delegates or {})
+        if str(src) not in children and str(src) not in _SKIP_ENTRY
+    ]
+    if len(roots) == 1:
+        return roots[0]
+    hinted = str(hinted or "").strip()
+    ids = {str(agent.get("id") or "") for agent in agents if isinstance(agent, dict)}
+    if hinted not in _SKIP_ENTRY and hinted in ids:
+        return hinted
+    if roots:
+        return roots[0]
+    for agent in agents:
+        aid = str((agent or {}).get("id") or "")
+        if aid not in _SKIP_ENTRY:
+            return aid
+    return ""
+
+
+def snapshot_from_records(records: list[dict[str, Any]]) -> dict[str, Any]:
+    """Infer a topology snapshot from native events (no MAS YAML required)."""
+    agents: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    hinted = ""
+    delegates: dict[str, list[str]] = {}
+    for record in records:
+        if not isinstance(record, dict):
+            continue
+        kind = str(record.get("kind") or "")
+        aid = str(record.get("agent_id") or "").strip()
+        if aid and aid not in {"mas", "user"} and aid not in seen:
+            seen.add(aid)
+            agents.append({"id": aid, "tools": [], "skills": []})
+        if not hinted and aid not in _SKIP_ENTRY and kind in {"execution_start", "mas_call_start"}:
+            hinted = aid
+        if kind != "tool_call_start":
+            continue
+        tool = str(record.get("tool_name") or "")
+        peer = parse_delegate_tool_name(tool)
+        if not peer or not aid:
+            continue
+        peers = delegates.setdefault(aid, [])
+        if peer and peer not in peers:
+            peers.append(peer)
+        if peer and peer not in seen:
+            seen.add(peer)
+            agents.append({"id": peer, "tools": [], "skills": []})
+    if not delegates and len(agents) > 1:
+        hub, delegates = infer_implicit_delegates(agents, records, hinted)
+        if hub:
+            hinted = hub
+    return {
+        "kind": "mas_topology",
+        "entry": pick_entry(agents, delegates, hinted),
+        "user": "user",
+        "agents": agents,
+        "delegates_to": delegates,
+    }
+
+
+def merge_spec_snapshots(base: dict[str, Any] | None, extra: dict[str, Any] | None) -> dict[str, Any]:
+    """Union agents and delegates_to so a sparse MAS YAML still shows event peers."""
+    out = dict(base or {})
+    extra = extra or {}
+    agents: list[dict[str, Any]] = []
+    seen: set[str] = set()
+    for src in (out.get("agents"), extra.get("agents")):
+        for agent in src or []:
+            if not isinstance(agent, dict):
+                continue
+            aid = str(agent.get("id") or "").strip()
+            if not aid or aid in seen:
+                continue
+            seen.add(aid)
+            agents.append(agent)
+    delegates: dict[str, list[str]] = {}
+    for src in (out.get("delegates_to"), extra.get("delegates_to")):
+        if not isinstance(src, dict):
+            continue
+        for key, peers in src.items():
+            have = delegates.setdefault(str(key), [])
+            for peer in peers or []:
+                name = str(peer).strip()
+                if name and name not in have:
+                    have.append(name)
+                if name and name not in seen:
+                    seen.add(name)
+                    agents.append({"id": name, "tools": [], "skills": []})
+            if str(key) not in seen:
+                seen.add(str(key))
+                agents.append({"id": str(key), "tools": [], "skills": []})
+    out["agents"] = agents
+    out["delegates_to"] = delegates
+    out["entry"] = pick_entry(agents, delegates, str(out.get("entry") or extra.get("entry") or ""))
+    out.setdefault("user", extra.get("user") or out.get("user") or "user")
+    out.setdefault("kind", extra.get("kind") or "mas_topology")
+    return out
+
+
+def load_yaml_text(text: str) -> dict[str, Any]:
+    data = yaml.safe_load(text) or {}
+    return data if isinstance(data, dict) else {}