agentseed-mcp 0.3.0

package/server/engine/plugin.py

@@ -0,0 +1,367 @@
+"""AgentSeed Agent Plugins 1.0.0 conformance checker.
+
+Validates plugin.json / skills / mcp.json against the Agent Plugins spec
+(§5, §6, §7). Acts as the spec's missing official linter.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import json
+import os
+import re
+
+# ---------------------------------------------------------------------------
+# Agent Plugins 1.0.0 conformance constants
+# ---------------------------------------------------------------------------
+
+PLUGIN_TOP_LEVEL_FIELDS = {
+    "$schema", "name", "version", "description",
+    "author", "homepage", "repository", "license", "keywords", "extensions",
+}
+AUTHOR_FIELDS = {"name", "email", "url"}
+MCP_TOP_LEVEL_FIELDS = {"$schema", "mcpServers"}
+_PLUGIN_NAME_RE = re.compile(r"^[a-z0-9](?:[a-z0-9.\-]*[a-z0-9])?$")
+_SKILL_NAME_RE = re.compile(r"^[a-z0-9](?:[a-z0-9\-]*[a-z0-9])?$")
+
+
+def _check_plugin_name(name: str) -> list[str]:
+    """Validate plugin.json ``name`` against §5.5 naming constraints."""
+    errs: list[str] = []
+    if not isinstance(name, str):
+        return ["plugin.json 'name' must be a string"]
+    if not (1 <= len(name) <= 64):
+        errs.append(f"plugin.json 'name' length {len(name)} not in 1..64")
+    if not _PLUGIN_NAME_RE.match(name):
+        errs.append(
+            f"plugin.json 'name' ({name!r}) must be lowercase alphanumeric "
+            "with - and . only, start and end alphanumeric, no '--' or '..'"
+        )
+    if "--" in name:
+        errs.append("plugin.json 'name' must not contain consecutive hyphens '--'")
+    if ".." in name:
+        errs.append("plugin.json 'name' must not contain consecutive dots '..'")
+    return errs
+
+
+def _parse_plugin_json(plugin_dir: str) -> tuple[dict, list[str]]:
+    """Load and return (plugin_data, errors) from plugin.json."""
+    pj = os.path.join(plugin_dir, "plugin.json")
+    errors: list[str] = []
+    if not os.path.isfile(pj):
+        errors.append("Missing root plugin.json (spec requires checking root plugin.json)")
+        return {}, errors
+    try:
+        with open(pj, encoding="utf-8") as fh:
+            data = json.load(fh)
+    except Exception as exc:  # noqa: BLE001
+        errors.append(f"plugin.json is not valid JSON: {exc}")
+        return {}, errors
+    if not isinstance(data, dict):
+        errors.append("plugin.json top level must be a JSON object")
+        return {}, errors
+    return data, errors
+
+
+def _parse_frontmatter(skill_md_path: str) -> dict:
+    """Extract name/description from a SKILL.md frontmatter block.
+
+    Uses PyYAML when available for full YAML coverage (nested maps, lists,
+    quoting rules); falls back to a zero-dependency YAML-lite parser that
+    handles ``key: value`` and folded scalars (``description: >-`` followed
+    by indented lines).
+    """
+    try:
+        with open(skill_md_path, encoding="utf-8") as fh:
+            content = fh.read()
+    except OSError:
+        return {}
+    if not content.startswith("---"):
+        return {}
+    end_m = re.search(r"^---\s*$", content[3:], re.MULTILINE)
+    if end_m is None:
+        return {}
+    block = content[3:3 + end_m.start()]
+
+    try:
+        import yaml  # type: ignore import-not-found
+
+        parsed = yaml.safe_load(block)
+        return parsed if isinstance(parsed, dict) else {}
+    except ImportError:
+        pass
+    except Exception:  # malformed YAML -> fall through to the lite parser
+        pass
+
+    out: dict = {}
+    lines = block.splitlines()
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        m = re.match(r"^([A-Za-z0-9\-]+):\s*(.*)$", line)
+        if not m:
+            i += 1
+            continue
+        key, value = m.group(1), m.group(2).strip()
+        if value in (">", ">-", "|", "|-"):
+            folded: list[str] = []
+            i += 1
+            while i < len(lines) and (lines[i].startswith(" ") or lines[i] == ""):
+                if lines[i].strip():
+                    folded.append(lines[i].strip())
+                i += 1
+            out[key] = " ".join(folded)
+            continue
+        out[key] = value
+        i += 1
+    return out
+
+
+def _check_skill_dir(skill_root: str, entry: str) -> list[str]:
+    """Validate one skills/<entry>/ against Agent Skills spec (via §7.1)."""
+    errs: list[str] = []
+    skill_md = os.path.join(skill_root, entry, "SKILL.md")
+    if not os.path.isfile(skill_md):
+        errs.append(f"skills/{entry}/ missing required SKILL.md")
+        return errs
+    fm = _parse_frontmatter(skill_md)
+    name = fm.get("name", "")
+    if not name:
+        errs.append(f"skills/{entry}/SKILL.md missing required frontmatter 'name'")
+    elif name != entry:
+        errs.append(
+            f"skills/{entry}/SKILL.md frontmatter 'name' ({name}) must match "
+            f"directory name ({entry})"
+        )
+    elif not _SKILL_NAME_RE.match(name):
+        errs.append(
+            f"skills/{entry}/SKILL.md 'name' must be lowercase alphanumeric "
+            "with hyphens only, not starting/ending with a hyphen"
+        )
+    desc = fm.get("description", "")
+    if not desc:
+        errs.append(f"skills/{entry}/SKILL.md missing required frontmatter 'description'")
+    elif len(desc) > 1024:
+        errs.append(f"skills/{entry}/SKILL.md 'description' exceeds 1024 chars")
+    return errs
+
+
+def _is_loopback_address(host: str) -> bool:
+    """Check if host is loopback (localhost hostname, 127.0.0.0/8, ::1).
+
+    Uses stdlib ``ipaddress`` instead of a hand-rolled IPv4-only check.
+    """
+    if host.lower() in ("localhost",):
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
+def _check_mcp_servers(m: dict, errors: list[str]) -> None:
+    """Validate the mcpServers section of mcp.json."""
+    servers = m.get("mcpServers", {})
+    if not isinstance(servers, dict):
+        errors.append("mcp.json 'mcpServers' must be an object")
+        return
+    for sname, cfg in servers.items():
+        if not isinstance(cfg, dict):
+            errors.append(f"mcp.json server '{sname}' must be an object")
+            continue
+        stype = cfg.get("type")
+        if stype not in ("stdio", "streamable-http", "sse"):
+            errors.append(
+                f"mcp.json server '{sname}' missing/unknown 'type' "
+                "(must be stdio | streamable-http | sse)"
+            )
+            continue
+        allowed_fields = {"stdio": {"type", "command", "args", "env", "cwd"},
+                          "streamable-http": {"type", "url", "headers"},
+                          "sse": {"type", "url", "headers"}}[stype]
+        for key in cfg:
+            if key not in allowed_fields:
+                errors.append(
+                    f"mcp.json server '{sname}' has unknown field '{key}' "
+                    f"for type '{stype}' (closed variant: only "
+                    f"{sorted(allowed_fields)})"
+                )
+        if stype == "stdio":
+            command = cfg.get("command")
+            if not command:
+                errors.append(f"mcp.json server '{sname}' (stdio) missing required 'command'")
+            elif not isinstance(command, str):
+                errors.append(f"mcp.json server '{sname}' 'command' must be a string")
+            elif not (command.startswith("./")
+                      or re.fullmatch(r"[A-Za-z0-9._\-]+", command)):
+                errors.append(
+                    f"mcp.json server '{sname}' 'command' must be a single "
+                    "executable token or a plugin-relative './...' path"
+                )
+            args = cfg.get("args")
+            if args is not None and (
+                not isinstance(args, list)
+                or any(not isinstance(a, str) for a in args)
+            ):
+                errors.append(f"mcp.json server '{sname}' 'args' must be an array of strings")
+            env = cfg.get("env")
+            if env is not None:
+                if not isinstance(env, dict) or any(
+                    not isinstance(v, str) for v in env.values()
+                ):
+                    errors.append(
+                        f"mcp.json server '{sname}' 'env' must be an object of strings"
+                    )
+                else:
+                    for reserved in ("PLUGIN_ROOT", "PLUGIN_DATA"):
+                        if reserved in env:
+                            errors.append(
+                                f"mcp.json server '{sname}' 'env' must not define "
+                                f"reserved variable '{reserved}'"
+                            )
+            cwd = cfg.get("cwd")
+            if cwd is not None and not (
+                cwd == "${PLUGIN_ROOT}"
+                or cwd.startswith("${PLUGIN_ROOT}/")
+                or cwd == "${PLUGIN_DATA}"
+                or cwd.startswith("${PLUGIN_DATA}/")
+                or cwd.startswith("./")
+            ):
+                errors.append(
+                    f"mcp.json server '{sname}' 'cwd' must be './relative', "
+                    "${PLUGIN_ROOT}[-rooted] or ${PLUGIN_DATA}[-rooted]"
+                )
+        else:
+            url = cfg.get("url")
+            if not url:
+                errors.append(f"mcp.json server '{sname}' missing required 'url'")
+            elif isinstance(url, str):
+                parsed = re.match(r"^https?://([^/?#]*)(.*)$", url)
+                if "#" in url:
+                    errors.append(
+                        f"mcp.json server '{sname}' 'url' must not contain a fragment"
+                    )
+                if "@" in parsed.group(1):
+                    errors.append(
+                        f"mcp.json server '{sname}' 'url' must not contain user information"
+                    )
+                host = (parsed.group(1).split("@")[-1] or "").rsplit(":", 1)[0].strip("[]")
+                if (
+                    url.startswith("http://")
+                    and host.lower() not in ("localhost", "::1")
+                    and not _is_loopback_address(host)
+                ):
+                    errors.append(
+                        f"mcp.json server '{sname}' non-loopback 'url' must use HTTPS"
+                    )
+            headers = cfg.get("headers")
+            if headers is not None and (
+                not isinstance(headers, dict)
+                or any(not isinstance(v, str) for v in headers.values())
+                or len({k.lower() for k in headers}) != len(headers)
+            ):
+                errors.append(
+                    f"mcp.json server '{sname}' 'headers' must be an object of "
+                    "strings without duplicate (case-insensitive) names"
+                )
+
+
+def check_plugin_conformance(plugin_dir: str) -> dict:
+    """Validate a directory against Agent Plugins 1.0.0 (§5/§6/§7).
+
+    Strict linter: closed-schema top-level fields, ``name`` constraints,
+    SKILL.md frontmatter, mcp.json fields and cwd form.
+
+    Returns:
+        {"ok": bool, "errors": [...], "warnings": [...]}
+    """
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    # ---- §5 manifest ------------------------------------------------------
+    data, pe = _parse_plugin_json(plugin_dir)
+    errors.extend(pe)
+
+    if data:
+        for key in data:
+            if key not in PLUGIN_TOP_LEVEL_FIELDS:
+                errors.append(
+                    f"plugin.json has unknown top-level field '{key}' "
+                    f"(closed schema: only {sorted(PLUGIN_TOP_LEVEL_FIELDS)})"
+                )
+        if data.get("$schema") != "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json":
+            errors.append("plugin.json $schema missing or not the 1.0.0 address")
+        if "name" not in data:
+            errors.append("plugin.json missing required field 'name'")
+        else:
+            errors.extend(_check_plugin_name(data["name"]))
+        for field, ftype in (("version", str), ("description", str),
+                             ("homepage", str), ("repository", str), ("license", str)):
+            if field in data and not isinstance(data[field], ftype):
+                errors.append(f"plugin.json '{field}' must be a string")
+        if "keywords" in data and (
+            not isinstance(data["keywords"], list)
+            or any(not isinstance(k, str) for k in data["keywords"])
+        ):
+            errors.append("plugin.json 'keywords' must be an array of strings")
+        if "author" in data:
+            author = data["author"]
+            if not isinstance(author, dict):
+                errors.append("plugin.json 'author' must be an object")
+            else:
+                for key in author:
+                    if key not in AUTHOR_FIELDS:
+                        errors.append(
+                            f"plugin.json 'author' has unknown field '{key}' "
+                            f"(only {sorted(AUTHOR_FIELDS)} allowed)"
+                        )
+                for key, value in author.items():
+                    if not isinstance(value, str):
+                        errors.append(f"plugin.json 'author.{key}' must be a string")
+
+    # ---- §6 skills ---------------------------------------------------------
+    skills_dir = os.path.join(plugin_dir, "skills")
+    if os.path.isdir(skills_dir):
+        found_skill = False
+        for entry in sorted(os.listdir(skills_dir)):
+            if os.path.isdir(os.path.join(skills_dir, entry)):
+                found_skill = True
+                errors.extend(_check_skill_dir(skills_dir, entry))
+        if not found_skill:
+            msg = (
+                "No skills/ directory (pure-MCP plugin is conformant, but this "
+                "plugin is designed hybrid)"
+            )
+            warnings.append(msg)
+    else:
+        msg = (
+            "No skills/ directory (pure-MCP plugin is conformant, but this "
+            "plugin is designed hybrid)"
+        )
+        warnings.append(msg)
+
+    # ---- §7 mcp.json -------------------------------------------------------
+    mcp = os.path.join(plugin_dir, "mcp.json")
+    if os.path.isfile(mcp):
+        try:
+            with open(mcp, encoding="utf-8") as fh:
+                m = json.load(fh)
+        except Exception as exc:  # noqa: BLE001
+            errors.append(f"mcp.json is not valid JSON: {exc}")
+            m = {}
+        if not isinstance(m, dict):
+            errors.append("mcp.json top level must be a JSON object")
+            m = {}
+        for key in m:
+            if key not in MCP_TOP_LEVEL_FIELDS:
+                errors.append(
+                    f"mcp.json has unknown top-level field '{key}' "
+                    f"(only {sorted(MCP_TOP_LEVEL_FIELDS)} allowed)"
+                )
+        if m.get("$schema") != "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json":
+            errors.append("mcp.json $schema missing or not the 1.0.0 address")
+        _check_mcp_servers(m, errors)
+    else:
+        warnings.append("No mcp.json (pure-skill plugin is conformant)")
+
+    return {"ok": len(errors) == 0, "errors": errors, "warnings": warnings}

package/server/engine/sandbox.py

@@ -0,0 +1,287 @@
+"""AgentSeed deterministic execution channel.
+
+Runs a command (no shell) in a subprocess with timeout and captured output.
+Turns "tests pass" into an observed fact.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+import os
+import shutil
+import subprocess
+import threading
+
+
+def _decode(raw) -> str:
+    return raw.decode("utf-8", errors="replace") if isinstance(raw, bytes) else (raw or "")
+
+
+def _read_bounded(stream, cap: int, sink: list[str]) -> None:
+    """Drain a pipe stream into ``sink`` keeping only the last ``cap`` chars.
+
+    Truncation happens WHILE streaming (drop-from-front ring buffer), so a
+    child that emits gigabytes of output costs O(cap) memory instead of
+    O(output). ``sink`` receives the final tail once EOF is reached.
+    """
+    chunks: deque[str] = deque()
+    size = 0
+    while True:
+        data = stream.read(65536)
+        if not data:
+            break
+        text = data.decode("utf-8", errors="replace")
+        chunks.append(text)
+        size += len(text)
+        while chunks and size - len(chunks[0]) >= cap:
+            size -= len(chunks[0])
+            chunks.popleft()
+    sink.append("".join(chunks)[-cap:])
+
+
+def resolve_executable(command_name: str, base_dir: str | None = None) -> str | None:
+    """Resolve a command token to the absolute path the OS would execute.
+
+    Path-qualified tokens resolve against ``base_dir`` (the ``cwd`` the
+    command will actually run in) so the policy-checked path IS the executed
+    path — resolving a relative command against the server's own working
+    directory would let a caller-controlled ``cwd`` swap the binary after
+    the allowlist check. Bare names (``python``, ``pytest``) go through
+    ``PATH`` lookup via ``shutil.which`` — deliberately NOT the raw name:
+    on Windows, spawning a relative name lets CreateProcess search the
+    process's working directory first, so a malicious ``cwd`` could shadow
+    an allowlisted basename with a planted executable. Returns None when a
+    bare name cannot be resolved anywhere.
+    """
+    if not isinstance(command_name, str) or not command_name:
+        return None
+    has_sep = os.path.sep in command_name or (os.altsep and os.altsep in command_name)
+    if not has_sep:
+        found = shutil.which(command_name)
+        return os.path.abspath(found) if found else None
+    if os.path.isabs(command_name):
+        return command_name
+    if base_dir:
+        return os.path.abspath(os.path.join(base_dir, command_name))
+    return os.path.abspath(command_name)
+
+
+def _norm_path(path: str) -> str:
+    return os.path.normcase(os.path.normpath(os.path.abspath(path)))
+
+
+def _path_matches(resolved: str, entry: str) -> bool:
+    """Directory-prefix match with a mandatory separator boundary."""
+    entry_norm = _norm_path(entry)
+    return resolved == entry_norm or resolved.startswith(entry_norm + os.sep)
+
+
+def _name_matches(resolved: str, entry: str) -> bool:
+    """Bare-name entry: exact basename equality (with .exe tolerance)."""
+    res_base = os.path.basename(resolved)
+    entry_base = os.path.basename(os.path.normcase(entry.strip()))
+    return res_base == entry_base or res_base == f"{entry_base}.exe"
+
+
+def _matches_allowlist(resolved: str, prefixes: list[str]) -> bool:
+    """Pure check (never executes): basename or bounded path-prefix match."""
+    res_norm = _norm_path(resolved)
+    for entry in prefixes:
+        if not isinstance(entry, str) or not entry.strip():
+            continue
+        stripped = entry.strip()
+        if os.path.sep in stripped or (os.altsep and os.altsep in stripped):
+            if _path_matches(res_norm, stripped):
+                return True
+        elif _name_matches(res_norm, stripped):
+            return True
+    return False
+
+
+def _blocked(command_head, prefixes: list[str]) -> dict:
+    return {
+        "exit_code": -10,
+        "stdout": "",
+        "stderr": (f"blocked: '{command_head}' is not in sandbox_allowed_prefixes {prefixes}"),
+        "timed_out": False,
+    }
+
+
+def kill_tree(proc) -> None:
+    """Best-effort process-TREE termination, children included.
+
+    Windows: ``taskkill /F /T`` walks the PID tree. POSIX: the child was
+    spawned in its own session (``start_new_session=True``), so SIGKILL on
+    the process group reaps the whole tree. Falls back to killing the leader
+    alone when either mechanism is unavailable."""
+    if proc.poll() is not None:
+        return
+    if os.name == "nt":
+        try:
+            subprocess.run(
+                ["taskkill", "/F", "/T", "/PID", str(proc.pid)],
+                capture_output=True,
+                timeout=15,
+                creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+            )
+            return
+        except Exception:  # noqa: BLE001 - fall through to leader kill
+            pass
+    else:
+        try:
+            import signal
+
+            os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+            return
+        except Exception:  # noqa: BLE001 - fall through to leader kill
+            pass
+    try:
+        proc.kill()
+    except OSError:
+        pass
+
+
+# Environment scrubbing (opt-in via config ``sandbox_env: "scrub"``): drop
+# variables whose NAMES look credential-bearing. Best-effort denylist — a
+# courtesy leak-reduction measure, NOT a security boundary.
+_SECRET_MARKERS = (
+    "TOKEN",
+    "SECRET",
+    "PASSWD",
+    "PASSWORD",
+    "CREDENTIAL",
+    "API_KEY",
+    "ACCESS_KEY",
+    "PRIVATE_KEY",
+    "AUTH",
+)
+
+
+def build_env(env_mode: str | None):
+    if env_mode == "scrub":
+        return {
+            k: v
+            for k, v in os.environ.items()
+            if not any(marker in k.upper() for marker in _SECRET_MARKERS)
+        }
+    return None  # inherit
+
+
+def _run_command(command: list[str], timeout: int, cwd: str | None, on_proc=None, env=None) -> dict:
+    """Spawn + wait + capture. Shared by sync and async callers.
+
+    ``on_proc`` (optional callable taking the Popen) lets callers register the
+    live process for cancellation. stdin is DEVNULL: sandbox commands never read
+    interactive input, and inheriting a piped stdin can deadlock children at
+    startup on Windows (observed with MCP stdio servers). POSIX children get
+    their own session so ``kill_tree`` can signal the whole group.
+    """
+    try:
+        proc = subprocess.Popen(
+            command,
+            cwd=cwd,
+            env=env,
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+            start_new_session=(os.name != "nt"),
+            close_fds=True,
+        )
+    except FileNotFoundError as exc:
+        return {
+            "exit_code": -2,
+            "stdout": "",
+            "stderr": f"command not found: {exc}",
+            "timed_out": False,
+        }
+    except Exception as exc:  # noqa: BLE001
+        return {"exit_code": -9, "stdout": "", "stderr": f"run failed: {exc}", "timed_out": False}
+    if callable(on_proc):
+        on_proc(proc)
+    # Two reader threads keep the response bounded in MEMORY, not just at the
+    # end: each pipe is drained incrementally into a tail ring buffer, so a
+    # child writing unlimited output cannot balloon the process. Threads (not
+    # selectors) because Windows select() does not work on pipes.
+    stdout_buf: list[str] = []
+    stderr_buf: list[str] = []
+    reader_out = threading.Thread(
+        target=_read_bounded, args=(proc.stdout, 8000, stdout_buf), daemon=True
+    )
+    reader_err = threading.Thread(
+        target=_read_bounded, args=(proc.stderr, 4000, stderr_buf), daemon=True
+    )
+    reader_out.start()
+    reader_err.start()
+    timed_out = False
+    try:
+        proc.wait(timeout=max(1, min(int(timeout), 120)))
+    except subprocess.TimeoutExpired:
+        timed_out = True
+        kill_tree(proc)
+    reader_out.join(timeout=5)
+    reader_err.join(timeout=5)
+    return {
+        "exit_code": -1 if timed_out else proc.returncode,
+        "stdout": stdout_buf[0] if stdout_buf else "",
+        "stderr": stderr_buf[0] if stderr_buf else "",
+        "timed_out": timed_out,
+    }
+
+
+def sandbox_run(
+    command: list[str],
+    timeout: int = 30,
+    cwd: str | None = None,
+    allowed_prefixes: list[str] | None = None,
+    on_proc=None,
+    env_mode: str | None = None,
+) -> dict:
+    """Run a command as a subprocess (no shell) with a timeout.
+
+    Deterministic verification channel: turns "the test passes" into an
+    observed fact (exit code + output). No shell means no injection via args;
+    output is truncated to a bounded tail WHILE streaming, so even a child
+    that floods output cannot blow the server's memory.
+
+    ``allowed_prefixes`` (config: ``sandbox_allowed_prefixes``): when a
+    non-empty list, the first argument is resolved to the absolute path the
+    OS would actually run (PATH lookup for bare names — never a relative
+    spawn, which Windows resolves against the attacker-controllable ``cwd``),
+    then checked against the allowlist: entries without a path separator
+    match the resolved basename exactly (``python`` also accepts
+    ``python.exe``); entries WITH a separator must equal the resolved path or
+    be a directory-prefix of it with a separator boundary (so ``C:\\tools\\s``
+    cannot match ``C:\\tools\\safe\\x.exe``). Anything unresolved or
+    unmatched is refused with exit code -10 WITHOUT running, and matched
+    commands execute under their RESOLVED absolute path. None/empty =
+    unrestricted (command is passed through verbatim).
+
+    ``env_mode`` (config: ``sandbox_env``): "inherit" (default) passes the
+    server environment through; "scrub" drops credential-looking variable
+    names before spawn (best-effort denylist, see ``build_env``).
+
+    ``on_proc`` (advanced): invoked with the live Popen so async callers can
+    register it for cancellation. Timeouts and cancellations kill the whole
+    process tree (POSIX process group / Windows taskkill /T), not just the
+    direct child.
+
+    Returns:
+        {"exit_code": int, "stdout": str, "stderr": str, "timed_out": bool}
+    """
+    if not isinstance(command, list) or not command:
+        return {
+            "exit_code": -3,
+            "stdout": "",
+            "stderr": "command must be a non-empty list",
+            "timed_out": False,
+        }
+    if allowed_prefixes:
+        head = command[0]
+        resolved = resolve_executable(head, cwd)
+        if resolved is None or not _matches_allowlist(resolved, allowed_prefixes):
+            return _blocked(head, list(allowed_prefixes))
+        argv = [resolved, *command[1:]]
+    else:
+        argv = list(command)
+    return _run_command(argv, timeout, cwd, on_proc=on_proc, env=build_env(env_mode))