agent-capmap 0.1.0__py3-none-any.whl

agentcapmap/graph/__init__.py

@@ -0,0 +1,264 @@
+"""Per-agent capability graph: the union of tool capabilities with per-tool provenance.
+
+An agent is one client config. Only enabled servers count. A tool contributes to the
+graph only if it was enumerated and classified; everything else is reported as
+"not assessed" rather than guessed at.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+from agentcapmap.findings import AgentCapabilities, NotAssessed, ToolRef
+from agentcapmap.graph.server_attrs import LaunchSource, SourceTrust, launch_source, source_trust
+from agentcapmap.models import (
+    Agent,
+    ClassificationStatus,
+    EnumerationStatus,
+    Inventory,
+    Server,
+    ToolClassification,
+    ToolDefinition,
+    ToolTags,
+    Transport,
+)
+from agentcapmap.taxonomy import AXES, DEFAULTS
+
+
+class ApprovalGate(StrEnum):
+    REQUIRED = "required"  # reserved: a config that provably requires confirmation
+    NONE = "none"  # config explicitly auto-approves the tool
+    UNKNOWN = "unknown"  # config does not say; treated as "no gate" by default rules
+
+
+@dataclass(frozen=True)
+class ServerView:
+    agent_id: str
+    server: Server
+    launch: LaunchSource
+    trust: SourceTrust
+
+    @property
+    def name(self) -> str:
+        return self.server.name
+
+    @property
+    def remote(self) -> bool:
+        return self.server.transport is not Transport.STDIO
+
+    def field(self, name: str) -> str | bool:
+        if name == "auth":
+            return self.server.auth.method.value
+        if name == "transport":
+            return self.server.transport.value
+        if name == "remote":
+            return self.remote
+        if name == "version_pinned":
+            return self.launch.pin.value
+        if name == "source_trust":
+            return self.trust.value
+        raise KeyError(name)
+
+    def phrase(self, name: str) -> str:
+        if name == "auth":
+            evidence = ", ".join(self.server.auth.evidence) or "no credentials in config"
+            return f"auth={self.server.auth.method.value} ({evidence})"
+        if name == "version_pinned":
+            return f"launch spec: {self.launch.spec}" if self.launch.spec else "no package spec"
+        if name == "source_trust":
+            return f"source: {self.launch.source_id or 'unidentified'}"
+        if name in ("remote", "transport"):
+            return f"transport={self.server.transport.value}"
+        raise KeyError(name)
+
+
+@dataclass(frozen=True)
+class ToolView:
+    server: ServerView
+    tool: ToolDefinition
+    classification: ToolClassification
+    tags: ToolTags
+    approval_gate: ApprovalGate
+    approval_source: str | None
+
+    @property
+    def ref(self) -> str:
+        return f"{self.server.name}/{self.tool.name}"
+
+    def non_default_axes(self) -> list[str]:
+        return [axis for axis in AXES if getattr(self.tags, axis) != DEFAULTS[axis]]
+
+    def field(self, name: str) -> str | bool:
+        if name in AXES:
+            value: str | bool = getattr(self.tags, name)
+            return value
+        if name == "suspicious_description":
+            flag = self.classification.suspicious_description
+            return bool(flag and flag.flag)
+        if name == "any_capability":
+            return bool(self.non_default_axes())
+        if name == "approval_gate":
+            return self.approval_gate.value
+        raise KeyError(name)
+
+    def phrase(self, name: str) -> str | None:
+        if name in AXES:
+            return self.classification.evidence.get(name)
+        if name == "suspicious_description":
+            flag = self.classification.suspicious_description
+            return flag.reason if flag and flag.flag else None
+        if name == "any_capability":
+            parts = [
+                f"{axis}: {self.classification.evidence[axis]}"
+                for axis in self.non_default_axes()
+                if axis in self.classification.evidence
+            ]
+            return "; ".join(parts) or None
+        if name == "approval_gate":
+            source = self.approval_source
+            if self.approval_gate is ApprovalGate.NONE:
+                if source in ("alwaysAllow", "autoApprove", "trust"):
+                    return f"auto-approved via config key {source!r}"
+                return f"auto-approved: {source}" if source else "auto-approved"
+            if self.approval_gate is ApprovalGate.REQUIRED:
+                return f"approval required: {source}" if source else "approval required"
+            return "no approval setting found in config"
+        raise KeyError(name)
+
+    def unverified(self, name: str) -> bool:
+        return name in self.classification.unverified_evidence
+
+
+@dataclass
+class AgentView:
+    agent: Agent
+    servers: list[ServerView] = field(default_factory=list)
+    # Classified tools only: the inputs to tag-based rules.
+    tools: list[ToolView] = field(default_factory=list)
+    # Every enumerated tool name per server, classified or not (for shadowing checks).
+    tool_names: dict[str, list[str]] = field(default_factory=dict)
+    not_assessed: list[NotAssessed] = field(default_factory=list)
+
+
+def _matches(patterns: list[str], tool_name: str) -> bool:
+    return any(fnmatch.fnmatchcase(tool_name, p) for p in patterns)
+
+
+def _approval(server: Server, tool_name: str) -> tuple[ApprovalGate, str | None] | None:
+    """The tool's approval gate and its evidence, or None if the client removes the tool."""
+    approval = server.approval
+    if _matches(approval.denied_patterns, tool_name):
+        return None  # deny rule: the client never offers this tool to the model
+    if approval.auto_approve_all:
+        return ApprovalGate.NONE, next(iter(approval.sources), "trust")
+    if tool_name in approval.auto_approved_tools:
+        key = next((s for s in approval.sources if s != "trust"), "alwaysAllow")
+        return ApprovalGate.NONE, key
+    if _matches(approval.auto_approved_patterns, tool_name):
+        return ApprovalGate.NONE, "permissions.allow rule"
+    if approval.default_gate == "blocked":
+        return None  # calls that would need approval are refused outright
+    if approval.default_gate == "none":
+        return ApprovalGate.NONE, approval.default_reason or None
+    if approval.default_gate == "required":
+        return ApprovalGate.REQUIRED, approval.default_reason or None
+    return ApprovalGate.UNKNOWN, None
+
+
+def build_agent_view(agent: Agent, trusted_sources: list[str] | None = None) -> AgentView:
+    view = AgentView(agent=agent)
+    for server in agent.servers:
+        if server.disabled:
+            continue  # not reachable by the agent
+        launch = launch_source(server)
+        sv = ServerView(
+            agent_id=agent.id,
+            server=server,
+            launch=launch,
+            trust=source_trust(launch.source_id, trusted_sources),
+        )
+        view.servers.append(sv)
+
+        enumeration = server.enumeration
+        if enumeration is None:
+            view.not_assessed.append(
+                NotAssessed(
+                    agent_id=agent.id,
+                    server=server.name,
+                    reason="tools not enumerated (run scan with --enumerate)",
+                )
+            )
+            continue
+        if enumeration.status is not EnumerationStatus.OK:
+            reason = f"enumeration {enumeration.status.value}"
+            if enumeration.error:
+                reason += f": {enumeration.error}"
+            view.not_assessed.append(
+                NotAssessed(agent_id=agent.id, server=server.name, reason=reason)
+            )
+            continue
+
+        reachable = [t for t in enumeration.tools if _approval(server, t.name) is not None]
+        view.tool_names[server.name] = [t.name for t in reachable]
+        for tool in reachable:
+            result = tool.classification
+            if result is None or result.status is not ClassificationStatus.CLASSIFIED:
+                reason = (
+                    "not classified (run with --classify)"
+                    if result is None
+                    else f"unclassified: {result.error or 'no reason recorded'}"
+                )
+                view.not_assessed.append(
+                    NotAssessed(
+                        agent_id=agent.id, server=server.name, tool=tool.name, reason=reason
+                    )
+                )
+                continue
+            if result.tags is None:  # classified results always carry tags
+                continue
+            approval = _approval(server, tool.name)
+            if approval is None:
+                continue
+            gate, gate_source = approval
+            view.tools.append(
+                ToolView(
+                    server=sv,
+                    tool=tool,
+                    classification=result,
+                    tags=result.tags,
+                    approval_gate=gate,
+                    approval_source=gate_source,
+                )
+            )
+    return view
+
+
+def capabilities(view: AgentView) -> AgentCapabilities:
+    caps: dict[str, list[ToolRef]] = {}
+    for tv in view.tools:
+        for axis in tv.non_default_axes():
+            key = f"{axis}={str(getattr(tv.tags, axis)).lower()}"
+            caps.setdefault(key, []).append(
+                ToolRef(
+                    server=tv.server.name,
+                    tool=tv.tool.name,
+                    evidence=tv.phrase(axis),
+                    unverified=tv.unverified(axis),
+                )
+            )
+    for refs in caps.values():
+        refs.sort(key=lambda r: (r.server, r.tool))
+    return AgentCapabilities(
+        agent_id=view.agent.id,
+        client=view.agent.client,
+        config_path=view.agent.config_path,
+        capabilities=dict(sorted(caps.items())),
+        tools_total=sum(len(names) for names in view.tool_names.values()),
+        tools_assessed=len(view.tools),
+    )
+
+
+def build_views(inventory: Inventory, trusted_sources: list[str] | None = None) -> list[AgentView]:
+    return [build_agent_view(agent, trusted_sources) for agent in inventory.agents]

agentcapmap/graph/server_attrs.py

@@ -0,0 +1,164 @@
+"""Server-level attributes derived from config alone (never from the LLM).
+
+- version pinning: is the launched code fixed to an exact version or digest?
+- source id: a stable name for where the code comes from, for trust allowlists.
+
+Parsing uses the redacted command line stored in the inventory, so it works on saved
+inventories too. Package names and versions are not secrets and survive redaction.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import re
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import PurePath
+from urllib.parse import urlsplit
+
+from agentcapmap.models import Server, Transport
+
+
+class PinStatus(StrEnum):
+    PINNED = "pinned"
+    UNPINNED = "unpinned"
+    LOCAL = "local"  # code in a local file; versioned with the repo or machine
+    NOT_APPLICABLE = "not_applicable"  # remote server: nothing to pin client-side
+    UNKNOWN = "unknown"
+
+
+class SourceTrust(StrEnum):
+    TRUSTED = "trusted"
+    UNTRUSTED = "untrusted"
+    UNKNOWN = "unknown"  # no trusted_sources configured
+
+
+@dataclass(frozen=True)
+class LaunchSource:
+    pin: PinStatus
+    source_id: str | None  # e.g. "npm:@modelcontextprotocol/server-filesystem"
+    spec: str | None = None  # the package/image spec as written
+
+
+_EXACT_SEMVER = re.compile(r"^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.\-+]+)?$")
+_EXACT_PEP440 = re.compile(r"^\d+(?:\.\d+)*(?:(?:a|b|rc)\d+)?(?:\.post\d+)?(?:\.dev\d+)?$")
+_NPM_RUNNERS = {"npx", "bunx"}
+_PYTHON_RUNNERS = {"uvx"}
+_CONTAINER_RUNNERS = {"docker", "podman"}
+_SCRIPT_RUNNERS = {"node", "python", "python3", "deno", "bun", "tsx", "ts-node"}
+_SCRIPT_SUFFIXES = (".js", ".mjs", ".cjs", ".ts", ".py")
+# docker/podman run flags that take a separate value argument.
+_CONTAINER_VALUE_FLAGS = frozenset(
+    {
+        "-e", "--env", "--env-file", "-v", "--volume", "--mount", "--name", "-p", "--publish",
+        "--network", "--net", "-w", "--workdir", "-u", "--user", "--entrypoint", "-l",
+        "--label", "--platform", "--pull", "--cpus", "-m", "--memory", "--add-host",
+        "--cap-add", "--cap-drop", "--security-opt", "-h", "--hostname", "--ulimit",
+        "--tmpfs", "--device", "--dns", "--restart", "--runtime", "--shm-size", "--ipc",
+        "--pid", "--userns", "--log-driver", "--log-opt", "--gpus",
+    }
+)  # fmt: skip
+
+
+def _program(command: str | None) -> str:
+    if not command:
+        return ""
+    name = PurePath(command.replace("\\", "/")).name.lower()
+    return name.removesuffix(".exe").removesuffix(".cmd").removesuffix(".bat")
+
+
+def _first_positional(args: list[str], value_flags: frozenset[str] = frozenset()) -> int | None:
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg == "--":
+            return i + 1 if i + 1 < len(args) else None
+        if arg.startswith("-"):
+            if arg in value_flags and "=" not in arg:
+                i += 2
+                continue
+            i += 1
+            continue
+        return i
+    return None
+
+
+def _npm_spec(spec: str) -> LaunchSource:
+    # "@scope/name@1.2.3", "name@1.2.3", "name@latest", "name"
+    at = spec.rfind("@")
+    name, version = (spec[:at], spec[at + 1 :]) if at > 0 else (spec, "")
+    pin = PinStatus.PINNED if _EXACT_SEMVER.match(version) else PinStatus.UNPINNED
+    return LaunchSource(pin=pin, source_id=f"npm:{name}", spec=spec)
+
+
+def _pypi_spec(spec: str) -> LaunchSource:
+    # "name==1.2.3", "name@1.2.3" (uvx), "name@latest", "name>=1", "name"
+    if "==" in spec:
+        name, version = spec.split("==", 1)
+    elif "@" in spec:
+        name, version = spec.split("@", 1)
+    else:
+        name, version = re.split(r"[<>=!~\[]", spec, maxsplit=1)[0], ""
+    pin = PinStatus.PINNED if _EXACT_PEP440.match(version) else PinStatus.UNPINNED
+    return LaunchSource(pin=pin, source_id=f"pypi:{name.strip().lower()}", spec=spec)
+
+
+def _image_spec(image: str) -> LaunchSource:
+    if "@sha256:" in image:
+        name = image.split("@", 1)[0]
+        return LaunchSource(pin=PinStatus.PINNED, source_id=f"docker:{name}", spec=image)
+    # Tags are mutable, so anything short of a digest is not pinned.
+    last = image.rsplit("/", 1)[-1]
+    name = image.rsplit(":", 1)[0] if ":" in last else image
+    return LaunchSource(pin=PinStatus.UNPINNED, source_id=f"docker:{name}", spec=image)
+
+
+def launch_source(server: Server) -> LaunchSource:
+    if server.transport is not Transport.STDIO:
+        host = (urlsplit(server.url or "").hostname or "").lower()
+        return LaunchSource(PinStatus.NOT_APPLICABLE, f"url:{host}" if host else None)
+
+    program, args = _program(server.command), server.args
+    if program in _NPM_RUNNERS or (program == "npm" and args[:1] == ["exec"]):
+        rest = args[1:] if program == "npm" else args
+        idx = _first_positional(rest, frozenset({"-p", "--package"}))
+        if idx is not None:
+            return _npm_spec(rest[idx])
+    elif program in ("pnpm", "yarn") and args[:1] == ["dlx"]:
+        idx = _first_positional(args[1:])
+        if idx is not None:
+            return _npm_spec(args[1:][idx])
+    elif program in _PYTHON_RUNNERS or (program == "pipx" and args[:1] == ["run"]):
+        rest = args[1:] if program == "pipx" else args
+        if "--from" in rest and rest.index("--from") + 1 < len(rest):
+            return _pypi_spec(rest[rest.index("--from") + 1])
+        idx = _first_positional(rest, frozenset({"--python", "--with", "-p"}))
+        if idx is not None:
+            return _pypi_spec(rest[idx])
+    elif program in _CONTAINER_RUNNERS and args[:1] == ["run"]:
+        idx = _first_positional(args[1:], _CONTAINER_VALUE_FLAGS)
+        if idx is not None:
+            return _image_spec(args[1:][idx])
+    elif program in _SCRIPT_RUNNERS:
+        idx = _first_positional(args)
+        if idx is not None and args[idx].lower().endswith(_SCRIPT_SUFFIXES):
+            return LaunchSource(PinStatus.LOCAL, f"local:{args[idx]}", spec=args[idx])
+    # An explicit path to a script or binary: code already on disk, not fetched at launch.
+    if server.command and (
+        server.command.lower().endswith(_SCRIPT_SUFFIXES)
+        or "/" in server.command
+        or "\\" in server.command
+    ):
+        return LaunchSource(PinStatus.LOCAL, f"local:{server.command}", spec=server.command)
+    return LaunchSource(PinStatus.UNKNOWN, None)
+
+
+def source_trust(source_id: str | None, trusted_sources: list[str] | None) -> SourceTrust:
+    if not trusted_sources:
+        return SourceTrust.UNKNOWN
+    if source_id is None:
+        return SourceTrust.UNTRUSTED
+    # fnmatchcase: case-sensitive, no filesystem semantics; patterns come from the policy.
+    if any(fnmatch.fnmatchcase(source_id, pattern) for pattern in trusted_sources):
+        return SourceTrust.TRUSTED
+    return SourceTrust.UNTRUSTED

agentcapmap/limits.py

@@ -0,0 +1,35 @@
+"""Resource limits for untrusted input (config files, MCP server output).
+
+A hostile MCP server or config file must not be able to exhaust memory or CPU, or
+crash a reader thread. Everything read from outside goes through these bounds.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Final
+
+# One JSON-RPC message (stdio line, HTTP body, SSE event).
+MAX_MESSAGE_BYTES: Final = 8 * 1024 * 1024
+# One config file.
+MAX_CONFIG_BYTES: Final = 4 * 1024 * 1024
+# Tools accepted from a single server across all tools/list pages.
+MAX_TOOLS_PER_SERVER: Final = 5000
+# Unanswered server-to-client messages buffered while waiting for a response.
+MAX_QUEUED_MESSAGES: Final = 1000
+# Longest stderr line kept for diagnostics.
+MAX_STDERR_LINE_CHARS: Final = 2000
+
+
+class UntrustedJSONError(ValueError):
+    pass
+
+
+def loads_untrusted(text: str | bytes) -> Any:
+    """json.loads that turns pathological input (e.g. deep nesting) into a ValueError."""
+    try:
+        return json.loads(text)
+    except RecursionError:
+        raise UntrustedJSONError("JSON nested too deeply") from None
+    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise UntrustedJSONError(f"invalid JSON: {exc}") from None

agentcapmap/models.py

@@ -0,0 +1,186 @@
+"""Internal inventory model: Agent -> [Server] -> [Tool].
+
+Serialized fields are always redacted. Raw launch details needed to actually start a
+server live in `LaunchSpec`, which is excluded from serialization and from repr.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from agentcapmap import __version__
+
+INVENTORY_SCHEMA_VERSION = "1"
+
+
+class Transport(StrEnum):
+    STDIO = "stdio"
+    HTTP = "http"  # Streamable HTTP
+    SSE = "sse"  # legacy HTTP+SSE
+    WS = "ws"  # WebSocket (Claude Code); listed, not enumerated
+
+
+class AuthMethod(StrEnum):
+    NONE = "none"
+    STATIC = "static"
+    OAUTH = "oauth"
+    UNKNOWN = "unknown"
+
+
+class AuthHint(BaseModel):
+    method: AuthMethod
+    # Where the credential comes from, by name only: "env:GITHUB_TOKEN", "header:Authorization".
+    evidence: list[str] = Field(default_factory=list)
+
+
+class SourceLocation(BaseModel):
+    path: str
+    line: int | None = None
+
+
+class LaunchSpec(BaseModel):
+    """Unredacted launch details. Never serialized, never repr'd."""
+
+    model_config = ConfigDict(frozen=True)
+
+    command: str | None = None
+    args: list[str] = Field(default_factory=list)
+    env: dict[str, str] = Field(default_factory=dict)
+    env_file: str | None = None
+    cwd: str | None = None
+    url: str | None = None
+    headers: dict[str, str] = Field(default_factory=dict)
+    # Directory used to resolve ${workspaceFolder} and relative paths.
+    base_dir: str | None = None
+
+    def __repr__(self) -> str:
+        return "LaunchSpec(<redacted>)"
+
+    __str__ = __repr__
+
+
+class ToolTags(BaseModel):
+    """The six taxonomy axes (see schemas/tool-tags.schema.json)."""
+
+    data_access: Literal["none", "private_read", "secrets_read"]
+    untrusted_input: bool
+    egress: Literal["none", "internal", "external"]
+    mutation: Literal["none", "reversible_write", "destructive"]
+    execution: Literal["none", "sandboxed", "host"]
+    privilege: Literal["none", "identity_admin"]
+
+
+class SuspiciousDescription(BaseModel):
+    flag: bool
+    reason: str = ""
+
+
+class ClassificationStatus(StrEnum):
+    CLASSIFIED = "classified"
+    UNCLASSIFIED = "unclassified"
+
+
+class ToolClassification(BaseModel):
+    status: ClassificationStatus
+    # Set only when status is "classified".
+    tags: ToolTags | None = None
+    confidence: float | None = None
+    # Per-axis phrase justifying each non-default tag.
+    evidence: dict[str, str] = Field(default_factory=dict)
+    # Axes whose evidence phrase could not be found in the tool definition text.
+    unverified_evidence: list[str] = Field(default_factory=list)
+    suspicious_description: SuspiciousDescription | None = None
+    # Why the tool is unclassified.
+    error: str | None = None
+    # Provenance: results are only comparable under the same versions and model.
+    model: str | None = None
+    taxonomy_version: str
+    prompt_version: str
+    from_cache: bool = False
+
+
+class ToolDefinition(BaseModel):
+    name: str
+    description: str = ""
+    input_schema: dict[str, Any] = Field(default_factory=dict)
+    annotations: dict[str, Any] | None = None
+    definition_hash: str
+    classification: ToolClassification | None = None
+
+
+class EnumerationStatus(StrEnum):
+    OK = "ok"
+    ERROR = "error"
+    TIMEOUT = "timeout"
+    AUTH_REQUIRED = "auth_required"
+    SKIPPED = "skipped"
+
+
+class EnumerationResult(BaseModel):
+    status: EnumerationStatus
+    error: str | None = None
+    protocol_version: str | None = None
+    server_info: dict[str, Any] | None = None
+    tools: list[ToolDefinition] = Field(default_factory=list)
+    # Hash over the sorted tool definition hashes: changes if any tool changes.
+    definition_hash: str | None = None
+
+
+class ApprovalConfig(BaseModel):
+    """Whether a person must approve each tool call, as far as the client config shows.
+
+    Most clients do not record this, so `default_gate` is "unknown" unless a format knows
+    better (Claude Code: "required" in its default permission mode).
+    """
+
+    auto_approve_all: bool = False
+    # Exact tool names that skip approval (e.g. Cline `alwaysAllow`).
+    auto_approved_tools: list[str] = Field(default_factory=list)
+    # Glob patterns over tool names that skip approval (e.g. Claude Code allow rules).
+    auto_approved_patterns: list[str] = Field(default_factory=list)
+    # Glob patterns over tool names the client removes from the agent (deny rules).
+    denied_patterns: list[str] = Field(default_factory=list)
+    # Gate for tools no rule matches: "required" | "none" | "unknown" | "blocked"
+    # ("blocked": the client refuses calls that would need approval, e.g. dontAsk mode).
+    default_gate: Literal["required", "none", "unknown", "blocked"] = "unknown"
+    default_reason: str = ""
+    # Config keys or rules the settings came from, for evidence.
+    sources: list[str] = Field(default_factory=list)
+
+
+class Server(BaseModel):
+    name: str
+    transport: Transport
+    command: str | None = None
+    args: list[str] = Field(default_factory=list)
+    url: str | None = None
+    env: dict[str, str] = Field(default_factory=dict)
+    headers: dict[str, str] = Field(default_factory=dict)
+    auth: AuthHint
+    location: SourceLocation
+    disabled: bool = False
+    approval: ApprovalConfig = Field(default_factory=ApprovalConfig)
+    enumeration: EnumerationResult | None = None
+    launch: LaunchSpec = Field(default_factory=LaunchSpec, exclude=True, repr=False)
+
+
+class Agent(BaseModel):
+    id: str
+    client: str
+    config_path: str
+    servers: list[Server] = Field(default_factory=list)
+
+
+class DiscoveryError(BaseModel):
+    path: str
+    message: str
+
+
+class Inventory(BaseModel):
+    schema_version: str = INVENTORY_SCHEMA_VERSION
+    tool_version: str = __version__
+    agents: list[Agent] = Field(default_factory=list)
+    errors: list[DiscoveryError] = Field(default_factory=list)