my-pi-agent 0.1.0

package/src/my_agent_core/session/store.py

@@ -0,0 +1,131 @@
+# pyright: reportUnusedCallResult=false, reportAttributeAccessIssue=false
+"""会话仓库：root 目录下 create / list / open / delete（pig-mono SessionManager 的裁剪版）。"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+from uuid import uuid4
+
+from pydantic import BaseModel
+
+from .session import Session
+
+
+class SessionMeta(BaseModel):
+    """会话元信息（list() 用）。"""
+
+    id: str
+    path: Path
+    created_at: str
+    entries: int
+
+
+class SessionStore:
+    """会话仓库：一个会话一个 <workspace/root>/<id>.jsonl 文件（pig-mono 式 workspace 隔离）。"""
+
+    def __init__(
+        self,
+        root: str | Path = ".my_agent_core/sessions",
+        workspace: str | Path | None = None,
+    ):
+        """workspace 默认 Path.cwd()。会话目录 = workspace/root（root 为绝对路径则直接用）。
+
+        每个项目在 <workspace>/.my_agent_core/sessions/ 下建自己的会话目录，
+        create/list/open/delete/fork 全部限定在该目录内，跨项目天然隔离。
+        """
+        self.workspace = Path(workspace) if workspace else Path.cwd()
+        root_path = Path(root)
+        self.root = root_path if root_path.is_absolute() else self.workspace / root_path
+
+    def create(self) -> Session:
+        """新会话：写 <root>/<id>.jsonl（不含 system）。Session.cwd = workspace。"""
+        self.root.mkdir(parents=True, exist_ok=True)
+        while True:
+            sid = f"{datetime.now().strftime('%Y%m%d-%H%M%S')}-{uuid4().hex[:8]}"
+            path = self.root / f"{sid}.jsonl"
+            if not path.exists():
+                session = Session(path=path, cwd=str(self.workspace))
+                session.id = sid
+                session.save()
+                return session
+
+    def create_session(self) -> Session:
+        """创建新会话（等同于 self.create()）。"""
+        return self.create()
+
+    def list(self) -> list[SessionMeta]:
+        """全部会话，按 created_at 倒序（新→旧）。损坏/缺字段文件跳过。"""
+        metas: list[SessionMeta] = []
+        for f in self.root.glob("*.jsonl"):
+            try:
+                with open(f, encoding="utf-8") as fh:
+                    first_line = fh.readline()
+                    if not first_line:
+                        continue
+                    header = json.loads(first_line)
+                    entries = sum(1 for _ in fh)
+                sid = header.get("id")
+                created_at = header.get("createdAt") or header.get("created_at")
+                if not sid or created_at is None:
+                    continue
+                metas.append(
+                    SessionMeta(
+                        id=sid,
+                        path=f,
+                        created_at=str(created_at),
+                        entries=entries,
+                    )
+                )
+            except (json.JSONDecodeError, KeyError, OSError):
+                continue
+        metas.sort(key=lambda m: m.created_at, reverse=True)
+        return metas
+
+    def _resolve(self, id_or_prefix: str) -> Path:
+        """全 id 或唯一前缀 → 文件路径；未找到/歧义 → ValueError。"""
+        matches: list[Path] = []
+        for f in self.root.glob("*.jsonl"):
+            try:
+                with open(f, encoding="utf-8") as fh:
+                    header = json.loads(fh.readline())
+                if header.get("id", "").startswith(id_or_prefix):
+                    matches.append(f)
+            except (json.JSONDecodeError, KeyError):
+                continue
+        if not matches:
+            raise ValueError(f"Session not found: {id_or_prefix}")
+        if len(matches) > 1:
+            raise ValueError(
+                f"Ambiguous session prefix {id_or_prefix!r}: "
+                f"candidates {[m.stem for m in matches]}"
+            )
+        return matches[0]
+
+    def open(self, id_or_prefix: str) -> Session:
+        """按 id 或唯一前缀打开会话（恢复整棵树）。"""
+        return Session.load(self._resolve(id_or_prefix))
+
+    def open_session(self, id_or_prefix: str) -> Session:
+        """打开会话（等同于 self.open(id_or_prefix)）。"""
+        return self.open(id_or_prefix)
+
+    def delete(self, id_or_prefix: str) -> None:
+        """删除会话文件。未找到 → ValueError。"""
+        self._resolve(id_or_prefix).unlink()
+
+    def fork(self, id_or_prefix: str, entry_id: str) -> Session:
+        """从某会话 entry 分叉：复制根→entry 路径为新会话（新 id/路径，独立演化）。"""
+        src = self.open(id_or_prefix)
+        new = self.create()
+        for entry in src.tree.get_path_to_entry(entry_id):
+            if hasattr(entry, "message"):
+                _ = new.add_message(entry.role, entry.content, **entry.metadata)  # pyright: ignore[reportAttributeAccessIssue]
+        return new
+
+
+__all__ = [
+    "SessionMeta",
+    "SessionStore",
+]

package/src/my_agent_core/session/tree.py

@@ -0,0 +1,86 @@
+"""Pure in-memory DAG tree algorithms for session entries.
+
+Provides entry mapping indexing with duplicate ID protection, cycle detection,
+and path extraction from root to leaf, operating with zero I/O side-effects.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+from .entries import SessionEntry
+
+
+class SessionTreeError(ValueError):
+    """Raised when an illegal operation or cycle occurs in the session DAG tree."""
+
+
+def entries_by_id(entries: Sequence[SessionEntry]) -> dict[str, SessionEntry]:
+    """建立 entry_id 到 SessionEntry 的索引字典。遇到重复 ID 抛出 SessionTreeError。"""
+    by_id: dict[str, SessionEntry] = {}
+    for entry in entries:
+        if entry.id in by_id:
+            raise SessionTreeError(f"Duplicate entry id: {entry.id}")
+        by_id[entry.id] = entry
+    return by_id
+
+
+def path_to_entry(
+    entries: Sequence[SessionEntry] | Mapping[str, SessionEntry],
+    leaf_id: str,
+) -> list[SessionEntry]:
+    """从根节点回溯到 leaf_id 的有序路径条目列表（根节点在前，叶节点在后）。
+
+    遇到缺失父节点报错，遇到循环引用抛出带 'Cycle detected' 的 SessionTreeError。
+    """
+    if isinstance(entries, Mapping):
+        by_id = entries
+    else:
+        by_id = entries_by_id(entries)
+
+    if leaf_id not in by_id:
+        raise SessionTreeError(f"Entry {leaf_id} not found")
+
+    path: list[SessionEntry] = []
+    seen: set[str] = set()
+    curr_id: str | None = leaf_id
+
+    while curr_id is not None:
+        if curr_id in seen:
+            raise SessionTreeError(f"Cycle detected at entry {curr_id}")
+        seen.add(curr_id)
+
+        entry = by_id.get(curr_id)
+        if entry is None:
+            raise SessionTreeError(f"Missing parent entry: {curr_id}")
+
+        path.append(entry)
+        curr_id = entry.parent_id
+
+    path.reverse()
+    return path
+
+
+def lowest_common_ancestor(
+    entries: Sequence[SessionEntry] | Mapping[str, SessionEntry],
+    id1: str,
+    id2: str,
+) -> str | None:
+    """计算两个节点的最近公共祖先 (LCA) ID。若无公共祖先则返回 None。"""
+    path1 = [e.id for e in path_to_entry(entries, id1)]
+    path2 = [e.id for e in path_to_entry(entries, id2)]
+    ancestor: str | None = None
+    for a, b in zip(path1, path2, strict=False):
+        if a == b:
+            ancestor = a
+        else:
+            break
+    return ancestor
+
+
+__all__ = [
+    "SessionTreeError",
+    "entries_by_id",
+    "path_to_entry",
+    "lowest_common_ancestor",
+]

package/src/my_agent_core/skills.py

@@ -0,0 +1,149 @@
+"""skill 机制：数据模型 + 仓储发现 + 格式化（pig-mono 式三件套，模型侧无 read 工具）。
+
+SkillManager 为 Repository 形态：持有 dict 状态，构造即发现，查询/格式化全部
+收编为实例方法（对应 pig-mono 的 SkillManager 类；模块级函数版本见历史）。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+
+@dataclass(frozen=True)
+class Skill:
+    """一个技能：name 来自目录名，description 来自 frontmatter，content 是正文。"""
+
+    name: str
+    description: str
+    content: str  # frontmatter 之下的正文
+    file_path: Path  # 调试用；不暴露给模型
+
+
+def parse_frontmatter(text: str) -> tuple[dict[str, str], str]:
+    """首部 --- 换行 YAML 换行 --- → (字段 dict, body)。无 frontmatter → ({}, 全文)。
+    用 yaml.safe_load；坏 YAML → 降级 ({}, 全文)，不抛不告警。"""
+    header = "---\n"
+    if not text.startswith(header):
+        return {}, text
+    end = text.find("\n---\n", len(header))
+    if end == -1:
+        return {}, text
+    block = text[len(header) : end]
+    body = text[end + len("\n---\n") :].strip()
+    try:
+        fields = yaml.safe_load(block)
+    except yaml.YAMLError:
+        return {}, text
+    if not isinstance(fields, dict):
+        return {}, text
+    return {str(k): str(v) for k, v in fields.items()}, body
+
+
+class SkillManager:
+    """skill 仓储（Repository）：发现 + 按名索引 + 清单/调用文本生成。
+
+    发现规则（pig-mono 同款）：只扫每个来源目录的一层子目录，认 <name>/SKILL.md；
+    name = 目录名（不读 frontmatter name）。缺 description → 跳过该 skill。
+    隐藏目录（. 开头）跳过。目录不存在 → 静默跳过。容错全静默，不抛不告警。
+    """
+
+    def __init__(
+        self,
+        dirs: Sequence[str | Path] | None = None,
+        extra_dirs: Sequence[str | Path] | None = None,
+    ):
+        """构造即发现：None → 探测 <cwd>/.agents/skills（不存在 → 空，静默）；
+        [] → 显式禁用；非空 list → 只扫这些目录。extra_dirs 追加额外发现目录（如 Plugin 解构技能目录）。"""
+        self.skills: dict[str, Skill] = {}
+        if dirs is None:
+            dirs = [Path.cwd() / ".agents" / "skills"]
+        for root in dirs:
+            self._discover_dir(Path(root))
+        if extra_dirs:
+            for root in extra_dirs:
+                self._discover_dir(Path(root))
+
+    def _discover_dir(self, root: Path) -> None:
+        """扫单一来源目录的一层子目录（认 <name>/SKILL.md，或根级 SKILL.md 单技能简写）。"""
+        if not root.is_dir():
+            return
+        # 1. 根级单 SKILL.md 简写支持
+        root_skill = root / "SKILL.md"
+        if root_skill.is_file():
+            skill = self._load_one(root_skill)
+            if skill is not None:
+                self.skills[skill.name] = skill
+
+        # 2. 一层子目录 <child>/SKILL.md 扫描
+        for child in sorted(root.iterdir()):
+            if not child.is_dir() or child.name.startswith("."):
+                continue
+            skill_file = child / "SKILL.md"
+            if not skill_file.is_file():
+                continue
+            skill = self._load_one(skill_file)
+            if skill is not None:
+                self.skills[skill.name] = skill
+
+    def _load_one(self, path: Path) -> Skill | None:
+        """读单个 SKILL.md → Skill；任何失败/缺 description → None（静默）。"""
+        try:
+            text = path.read_text(encoding="utf-8-sig")
+        except OSError:
+            return None
+        meta, body = parse_frontmatter(text)
+        description = meta.get("description")
+        if not description:
+            return None
+        name = (meta.get("name") or "").strip() or path.parent.name
+        return Skill(name=name, description=description, content=body, file_path=path)
+
+    def get(self, name: str) -> Skill | None:
+        """按名查询（Repository 主查询）。"""
+        return self.skills.get(name)
+
+    def list(self) -> list[Skill]:
+        """全部 skills，发现顺序。"""
+        return list(self.skills.values())
+
+    def __len__(self) -> int:
+        return len(self.skills)
+
+    def __contains__(self, name: str) -> bool:
+        return name in self.skills
+
+    def format_prompt(self, names: Sequence[str] | None = None) -> str:
+        """全部（或指定名字子集）skills → XML 清单块；空 → 空串（进 system）。
+        names 给定只格式化这些名字（供 subagent skills 字段取子集）；未知名忽略。"""
+        skills = (
+            (self.skills[n] for n in names if n in self.skills)
+            if names is not None
+            else self.skills.values()
+        )
+        parts = ["<available_skills>"]
+        for s in skills:
+            parts.append("  <skill>")
+            parts.append(f"    <name>{s.name}</name>")
+            parts.append(f"    <description>{s.description}</description>")
+            parts.append("  </skill>")
+        if len(parts) == 1:
+            return ""
+        parts.append("</available_skills>")
+        return "\n".join(parts)
+
+    def format_invocation(self, name: str, instructions: str = "") -> str:
+        """按名取正文并包装 '<skill name="…" location="…">\\n{content}\\n</skill>'
+        + 可选附言（\\n\\n 衔接）。未知名 → ValueError（列可用名字）。"""
+        skill = self.get(name)
+        if skill is None:
+            available = ", ".join(sorted(self.skills)) or "(none)"
+            raise ValueError(f"Unknown skill '{name}'. Available: {available}")
+        block = (
+            f'<skill name="{skill.name}" location="{skill.file_path}">\n'
+            f"{skill.content}\n</skill>"
+        )
+        return f"{block}\n\n{instructions}" if instructions else block

package/src/my_agent_core/subagent_tasks.py

@@ -0,0 +1,170 @@
+"""subagent 委派的任务生命周期：SubagentTask 模型 + SubagentTaskStatus + SubagentTaskManager。
+
+委派逻辑（_filter_tools/_system_for）从 subagents.py 移入；make_task_tool 位于
+tools/builtin/task.py（工具桥，真实逻辑在 SubagentTaskManager）。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+from my_agent_core.session import Session
+from my_agent_core.subagents import DEFAULT_SUBAGENT, Subagent, SubagentManager
+from my_agent_core.tools import Tool
+
+if TYPE_CHECKING:
+    from my_agent_core.agent import Agent
+
+
+class SubagentTaskStatus(StrEnum):
+    """子代理委派任务三态。"""
+
+    RUNNING = "running"
+    COMPLETED = "completed"
+    ERROR = "error"
+
+
+@dataclass
+class SubagentTask:
+    """一次子代理委派执行句柄：有 id/状态/结果，可查询。"""
+
+    id: str
+    status: SubagentTaskStatus
+    result: str | None = None
+    error: str | None = None
+
+    def set_result(self, result: str) -> None:
+        """标记成功。"""
+        self.result = result
+        self.error = None
+        self.status = SubagentTaskStatus.COMPLETED
+
+    def set_error(self, error: str) -> None:
+        """标记失败。"""
+        self.error = error
+        self.result = None
+        self.status = SubagentTaskStatus.ERROR
+
+
+def _system_for(sub: Subagent, parent: Agent) -> str:
+    """子代理 system = 正文 + （若有 skills）子集清单；不收父 system prompt（Claude 官方语义）。"""
+    parts = [sub.content]
+    if sub.skills:
+        block = parent.skill_manager.format_prompt(sub.skills)
+        if block:
+            parts.append(block)
+    return "\n\n".join(p for p in parts if p)
+
+
+def _filter_tools(parent: Agent, sub: Subagent) -> list[Tool]:  # pyright: ignore[reportUndefinedVariable]
+    """父工具集按白/黑名单过滤；task、memory 与 task_* 永不出现（防递归与隔离）。"""
+    builtins = (
+        "task",
+        "memory",
+        "todo",
+        "task_create",
+        "task_update",
+        "task_get",
+        "task_list",
+        "todo_write",
+    )
+    tools = [t for t in parent.registry.list() if t.name not in builtins]
+    if sub.tools is not None:
+        allowed = set(sub.tools)
+        tools = [t for t in tools if t.name in allowed]
+    black = set(sub.disallowed_tools)
+    tools = [t for t in tools if t.name not in black]
+    return tools
+
+
+class SubagentTaskManager:
+    """子代理委派任务的生命周期管理器（对标 OpenHands TaskManager）。"""
+
+    def __init__(self, manager: SubagentManager, parent: Agent) -> None:
+        self._manager = manager  # 查 agent 定义
+        self._parent = parent  # 供 llm/工具集/skill_manager/max_iterations
+        self._counter = 0
+        self._active_agents: dict[
+            str, Agent
+        ] = {}  # 追踪运行中的子代理实例 (task_id -> Agent)
+
+    def steer_task(self, task_id: str, message: str) -> bool:
+        """向指定运行中的子代理发送 Steer 转向指令。"""
+        agent = self._active_agents.get(task_id)
+        if agent is not None:
+            agent.steer(message)
+            return True
+        return False
+
+    def follow_up_task(self, task_id: str, message: str) -> bool:
+        """向指定运行中的子代理发送 Follow-up 追问指令。"""
+        agent = self._active_agents.get(task_id)
+        if agent is not None:
+            agent.follow_up(message)
+            return True
+        return False
+
+    async def start_task(
+        self, prompt: str, subagent_type: str = "default"
+    ) -> SubagentTask:
+        """异步：建 SubagentTask(RUNNING) → spawn → run → 更新状态 → 返回。"""
+        task = self._create_task(subagent_type)
+        try:
+            task.set_result(await self._run(prompt, subagent_type, task.id))
+        except Exception as exc:
+            task.set_error(str(exc))
+        return task
+
+    def _create_task(self, _subagent_type: str) -> SubagentTask:
+        self._counter += 1
+        return SubagentTask(
+            id=f"task_{self._counter:08x}", status=SubagentTaskStatus.RUNNING
+        )
+
+    async def _run(self, prompt: str, subagent_type: str, task_id: str) -> str:
+        """查定义 → 建独立 session → 过滤工具 → spawn 子 Agent → run → 返回最终文本。"""
+        from my_agent_core.agent import Agent  # 延迟 import 避循环
+
+        sub = self._manager.get(subagent_type)
+        if sub is None and subagent_type == "default":
+            sub = DEFAULT_SUBAGENT
+        if sub is None:
+            available = ", ".join(sorted(self._manager.subagents)) or "(none)"
+            raise ValueError(
+                f"Unknown subagent '{subagent_type}'. Available: {available}"
+            )
+        child_session = Session(
+            path=self._parent.session.path.parent
+            / "subagents"
+            / f"agent-{task_id}.jsonl",
+            cwd=self._parent.session.cwd,
+            metadata={
+                "agent_type": subagent_type,
+                "parent_session_id": self._parent.session.id,
+            },
+        )
+        child_session.save()
+        child = Agent(
+            llm=self._parent.llm,
+            tools=_filter_tools(self._parent, sub),
+            session=child_session,
+            system_prompt=_system_for(sub, self._parent),
+            model=sub.model,
+            max_iterations=sub.max_turns
+            if sub.max_turns is not None
+            else self._parent.max_iterations,
+            skill_dirs=[],  # skill 清单已由 _system_for 拼入
+            subagent_dirs=[],  # 防递归：禁用子代理再探测
+            memory_dir=False,  # 隔离：子代理禁用长期记忆探测与维护
+            task_store=False,  # 隔离：子代理禁用任务看板探测与维护
+            plugin_dirs=[],  # 隔离：子代理禁用插件再探测（防递归注册 task 工具）
+        )
+        self._active_agents[task_id] = child
+        try:
+            return (await child.run(prompt)) or "(no summary)"
+        except Exception as exc:
+            raise RuntimeError(f"Subagent '{subagent_type}' failed: {exc}") from exc
+        finally:
+            _ = self._active_agents.pop(task_id, None)

package/src/my_agent_core/subagents.py

@@ -0,0 +1,148 @@
+"""subagent 机制：数据模型 + 仓储发现 + 清单格式化（对标 Claude Code 生态 agent 定义）。
+
+SubagentManager 为 Repository 形态（对标 SkillManager）：构造即发现 agents/*.md，
+按名索引，清单格式化进 system prompt。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+from my_agent_core.skills import parse_frontmatter
+
+
+@dataclass(frozen=True)
+class Subagent:
+    """一个子代理定义：name 来自 frontmatter（缺省文件名），description 供主模型
+    触发选择，content 是正文（= 子代理 system prompt，不收父 system prompt）。"""
+
+    name: str
+    description: str
+    content: str
+    file_path: Path
+    model: str | None = None  # 缺省 inherit = 继承父模型
+    effort: str | None = (
+        None  # v1 解析但不消费（SDK 无统一 effort 参数，端到端映射留 LLM 层演进）
+    )
+    max_turns: int | None = None  # maxTurns（缺省继承父 max_iterations）
+    tools: tuple[str, ...] | None = None  # 白名单；None=继承父全部
+    disallowed_tools: tuple[str, ...] = ()  # 黑名单
+    skills: tuple[str, ...] | None = None  # 子代理 skill 名（清单拼 system）
+
+
+DEFAULT_SUBAGENT_SYSTEM = (
+    "You are a subagent. Complete the given task independently, "
+    "then summarize your findings."
+)
+DEFAULT_SUBAGENT = Subagent(
+    name="default",
+    description="A general-purpose subagent for standalone tasks.",
+    content=DEFAULT_SUBAGENT_SYSTEM,
+    file_path=Path("<builtin>"),
+)
+
+
+def _split_csv(value: object) -> tuple[str, ...] | None:
+    """frontmatter 逗号分隔字符串 → tuple；非字符串/空 → None（保留缺省）。"""
+    if not isinstance(value, str):
+        return None
+    parts = tuple(p.strip() for p in value.split(",") if p.strip())
+    return parts if parts else None
+
+
+def _parse_max_turns(value: object) -> int | None:
+    """maxTurns：str 或 int → int；坏值/其他 → None。"""
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str):
+        try:
+            return int(value.strip())
+        except ValueError:
+            return None
+    return None
+
+
+class SubagentManager:
+    """subagent 仓储：发现 agents/*.md + 按名索引 + 清单格式化。"""
+
+    def __init__(
+        self,
+        dirs: Sequence[str | Path] | None = None,
+        extra_dirs: Sequence[str | Path] | None = None,
+    ):
+        """构造即发现：None → 探测 <cwd>/.agents/agents（不存在 → 空，静默）；
+        [] → 显式禁用；非空 → 只扫这些目录。extra_dirs 追加额外发现目录（如 Plugin 解构子代理目录）。"""
+        self.subagents: dict[str, Subagent] = {}
+        if dirs is None:
+            dirs = [Path.cwd() / ".agents" / "agents"]
+        for root in dirs:
+            self._discover_dir(Path(root))
+        if extra_dirs:
+            for root in extra_dirs:
+                self._discover_dir(Path(root))
+
+    def _discover_dir(self, root: Path) -> None:
+        """扫一层 *.md（不递归、不认子目录、跳过 README/隐藏文件）。同名后覆盖。"""
+        if not root.is_dir():
+            return
+        for child in sorted(root.iterdir()):
+            if child.is_dir() or child.suffix.lower() != ".md":
+                continue
+            if child.name.startswith(".") or child.name.lower() == "readme.md":
+                continue
+            sub = self._load_one(child)
+            if sub is not None:
+                self.subagents[sub.name] = sub
+
+    def _load_one(self, path: Path) -> Subagent | None:
+        """读单文件 → Subagent；读失败/坏 YAML/缺 description → None（静默）。"""
+        try:
+            text = path.read_text(encoding="utf-8-sig")
+        except OSError:
+            return None
+        meta, body = parse_frontmatter(text)
+        description = (meta.get("description") or "").strip()
+        if not description:
+            return None
+        name = (meta.get("name") or "").strip() or path.stem
+        return Subagent(
+            name=name,
+            description=description,
+            content=body,
+            file_path=path,
+            model=meta.get("model") or None,
+            effort=meta.get("effort") or None,
+            max_turns=_parse_max_turns(meta.get("maxTurns")),
+            tools=_split_csv(meta.get("tools")),
+            disallowed_tools=_split_csv(meta.get("disallowedTools")) or (),
+            skills=_split_csv(meta.get("skills")),
+        )
+
+    def get(self, name: str) -> Subagent | None:
+        return self.subagents.get(name)
+
+    def list(self) -> list[Subagent]:
+        return list(self.subagents.values())
+
+    def __len__(self) -> int:
+        return len(self.subagents)
+
+    def __contains__(self, name: str) -> bool:
+        return name in self.subagents
+
+    def format_prompt(self) -> str:
+        """全部 agents → XML 清单块（名字 + description）；空 → 空串（进 system）。"""
+        if not self.subagents:
+            return ""
+        parts = ["<available_agents>"]
+        for s in self.subagents.values():
+            parts.append("  <agent>")
+            parts.append(f"    <name>{s.name}</name>")
+            parts.append(f"    <description>{s.description}</description>")
+            parts.append("  </agent>")
+        parts.append("</available_agents>")
+        return "\n".join(parts)