devops-bot-sdk 1.6.28__tar.gz → 1.6.32__tar.gz

{devops_bot_sdk-1.6.28 → devops_bot_sdk-1.6.32}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.6.28
+Version: 1.6.32
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.6.28 → devops_bot_sdk-1.6.32}/devops_bot_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.6.28
+Version: 1.6.32
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.6.28 → devops_bot_sdk-1.6.32}/devops_bot_sdk.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ devops_bot_sdk.egg-info/requires.txt
 devops_bot_sdk.egg-info/top_level.txt
 sdk/__init__.py
 sdk/agentd.py
+sdk/browser_profile.py
 sdk/cli.py
 sdk/client.py
 sdk/config.py
@@ -36,6 +37,7 @@ sdk/test.py
 sdk/test_pipeline.py
 sdk/ticket_fields.py
 sdk/updater.py
+sdk/url_access.py
 sdk/vps_health.py
 sdk/agents/__init__.py
 sdk/agents/activity.py
@@ -119,6 +121,7 @@ tests/test_agent_workspace_settings.py
 tests/test_agents_connectors_builder.py
 tests/test_allowed_tools_config.py
 tests/test_auto_agent_dispatch.py
+tests/test_browser_profile.py
 tests/test_client_jira_projects.py
 tests/test_config_token_diagnostics.py
 tests/test_configure_token_owner.py
@@ -154,4 +157,5 @@ tests/test_ticket_run_resolve_by_id.py
 tests/test_ticket_speed_fixes.py
 tests/test_update_timer.py
 tests/test_updater_extras.py
+tests/test_url_access.py
 tests/test_vps_health.py

{devops_bot_sdk-1.6.28 → devops_bot_sdk-1.6.32}/sdk/__init__.py

@@ -1,6 +1,6 @@
 """AgentOS Desktop SDK — thin HTTPS/SSE client for the Electron app.
 
-Version: 1.6.28
+Version: 1.6.32
 
 Public surface:
   BackendClient.from_config()        — create client from ~/.agentos/config.toml
@@ -34,7 +34,7 @@ Rules:
   - All data egress through submit_webhook only
 """
 
-__version__ = "1.6.28"   # SINGLE SOURCE OF TRUTH — bump on every change; pyproject,
+__version__ = "1.6.32"   # SINGLE SOURCE OF TRUTH — bump on every change; pyproject,
 __author__  = "AgentOS"   # sdk.client.SDK_VERSION and the UI server version all read this.
 
 from sdk.client import BackendClient

devops_bot_sdk-1.6.32/sdk/browser_profile.py

@@ -0,0 +1,362 @@
+"""A browser profile the SDK owns, and the operator signs in to once.
+
+The generic answer to "read the link I am logged in to" is a browser, and the
+browser has to be one with sessions in it. Neither obvious candidate is:
+
+* **Chrome for Testing**, which ``design_verify/bootstrap`` installs for the
+  design loop, is a fresh binary with a blank profile. It is signed in to
+  nothing, so driving it answers every private link with a login page.
+* **The operator's own Chrome profile** cannot be driven either. Chrome 136 and
+  later refuse ``--remote-debugging-port`` while using the default user-data-dir
+  — deliberately, because allowing it is how session cookies get stolen — and a
+  second Chrome cannot open a profile the running one holds. Copying the profile
+  would work and is precisely the cookie-theft shape that decision exists to
+  prevent, so it is not done here either.
+
+So this module keeps a THIRD profile: ``~/.agentos/browser-profile``, belonging
+to the SDK. ``agentos browser login <url>`` opens a normal, visible window on it;
+the person signs in the way they would anywhere — password, SSO, MFA, whatever
+the site asks — and closes it. The persistent cookies that login writes stay in
+that directory, and every later read runs headless against the same directory and
+is therefore signed in too.
+
+Two properties make this the right trade:
+
+* **Nothing decrypts anything.** The SDK never reads the person's own cookie
+  store. It has its own profile, holding only sessions they deliberately signed
+  into for this purpose, in a directory they can delete in one command.
+* **No new dependency and no CDP.** ``chrome --headless=new --dump-dom <url>``
+  prints the rendered DOM to stdout. That is the entire mechanism: no WebSocket,
+  no Playwright, no driver to keep in step with the browser version.
+
+It is genuinely host-agnostic. Nothing here knows what GitHub or Outlook is — a
+site is readable if the person signed in to it, and the list of such sites is
+whatever they chose.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from contextlib import suppress
+from dataclasses import dataclass
+from functools import lru_cache
+from datetime import datetime, timezone
+from pathlib import Path
+from urllib.parse import urlparse
+
+logger = logging.getLogger(__name__)
+
+PROFILE_ENV = "AGENTOS_BROWSER_PROFILE"
+BINARY_ENV = "AGENTOS_BROWSER_BINARY"
+_SANDBOX_ENV = "AGENTOS_BROWSER_NO_SANDBOX"
+
+# Chromium family only: ``--dump-dom`` is a Chrome flag and has no Firefox
+# equivalent, and the whole point is one code path rather than a driver per
+# engine. Order is preference — the operator's everyday Chrome first, since a
+# site that works there is the one they will expect to work here.
+_CANDIDATES = (
+    "google-chrome", "google-chrome-stable", "chromium", "chromium-browser",
+    "microsoft-edge", "microsoft-edge-stable", "brave-browser",
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+)
+
+# A page is evidence, not an application: give it time to render and settle, then
+# take what is there. `--virtual-time-budget` fast-forwards timers so this costs
+# wall-clock only for the network, not for a site's animations.
+_VIRTUAL_TIME_MS = 12_000
+_FETCH_TIMEOUT_S = 60.0
+_REAP_TIMEOUT_S = 3.0
+_VERSION_TIMEOUT_S = 10.0
+
+
+def profile_dir() -> Path:
+    return Path(os.environ.get(PROFILE_ENV, "") or
+                (Path.home() / ".agentos" / "browser-profile")).expanduser()
+
+
+def sites_file() -> Path:
+    """Hosts the operator signed in to, RECORDED BY US as they do it.
+
+    Deliberately not derived from the profile's cookie database. `browser status`
+    needs to answer "what is this signed in to", and reading cookies to find out
+    — even our own — would put cookie-parsing code in the SDK, which is the thing
+    this design exists to avoid. A note we wrote ourselves is enough.
+    """
+    return profile_dir().parent / "browser-sites.json"
+
+
+@dataclass
+class Fetched:
+    """One headless read. ``html`` empty means it did not happen."""
+    html: str = ""
+    reason: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return bool(self.html)
+
+
+def find_browser() -> str:
+    """Path to a Chromium-family browser, or "". Honours ``AGENTOS_BROWSER_BINARY``."""
+    override = os.environ.get(BINARY_ENV, "").strip()
+    if override:
+        return override if (shutil.which(override) or Path(override).exists()) else ""
+    for name in _CANDIDATES:
+        found = shutil.which(name)
+        if found:
+            return found
+        if name.startswith("/") and Path(name).exists():
+            return name
+    return ""
+
+
+def is_available() -> bool:
+    return bool(find_browser())
+
+
+@lru_cache(maxsize=8)
+def _version_of(binary: str) -> str:
+    """``149.0.7827.200`` from ``chrome --version``, or "".
+
+    Cached per binary: a browser does not change version inside one process, and
+    this is a subprocess on the path of every read. Keyed on the path rather than
+    stored in a flag so an override pointing somewhere else is not answered with
+    the previous browser's version.
+    """
+    try:
+        out = subprocess.run([binary, "--version"], capture_output=True, text=True,
+                             timeout=_VERSION_TIMEOUT_S).stdout
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    for word in out.split():
+        if word[:1].isdigit() and word.count(".") >= 2:
+            return word.strip()
+    return ""
+
+
+def _version() -> str:
+    binary = find_browser()
+    return _version_of(binary) if binary else ""
+
+
+def user_agent() -> str:
+    """A non-headless UA for the browser we actually have.
+
+    New headless still announces ``HeadlessChrome``, and enough sites refuse it
+    that a page would come back as a block notice rather than the evidence. Built
+    from the installed version rather than hard-coded so it does not quietly go
+    stale into exactly the mismatch that gets a request flagged.
+    """
+    version = _version() or "140.0.0.0"
+    system = sys.platform
+    if system == "darwin":
+        os_part = "Macintosh; Intel Mac OS X 10_15_7"
+    elif system.startswith("win"):
+        os_part = "Windows NT 10.0; Win64; x64"
+    else:
+        os_part = f"X11; Linux {platform.machine() or 'x86_64'}"
+    return (f"Mozilla/5.0 ({os_part}) AppleWebKit/537.36 (KHTML, like Gecko) "
+            f"Chrome/{version} Safari/537.36")
+
+
+def _base_args() -> list[str]:
+    args = [
+        f"--user-data-dir={profile_dir()}",
+        "--no-first-run",
+        "--no-default-browser-check",
+        "--disable-background-networking",
+        "--disable-sync",                 # this profile is not anyone's identity
+        "--mute-audio",
+    ]
+    if os.environ.get(_SANDBOX_ENV, "").strip() in ("1", "true", "True"):
+        # Some containers cannot run the sandbox at all. Off by default: the
+        # sandbox is the thing standing between a hostile page and this machine.
+        args.append("--no-sandbox")
+    return args
+
+
+def busy_pid() -> int | None:
+    """The pid holding this profile, or None.
+
+    Chrome keeps one instance per user-data-dir; a second launch hands its
+    arguments to the first and exits, which for a headless read means an empty
+    answer with no error. Checking first turns that into a sentence the operator
+    can act on. A stale lock from a crash names a pid that is gone, and is
+    correctly reported as not busy.
+    """
+    lock = profile_dir() / "SingletonLock"
+    try:
+        target = os.readlink(lock)
+    except (OSError, ValueError):
+        return None
+    # "<hostname>-<pid>"
+    _, _, raw = target.rpartition("-")
+    try:
+        pid = int(raw)
+    except ValueError:
+        return None
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return None
+    except PermissionError:
+        return pid          # alive, owned by someone else
+    except OSError:
+        return None
+    return pid
+
+
+async def fetch_dom(url: str, *, timeout: float = _FETCH_TIMEOUT_S) -> Fetched:
+    """Render ``url`` headless in the signed-in profile and return its DOM.
+
+    ``--dump-dom`` prints the page AFTER scripts have run, which is what makes
+    this work on the single-page apps most internal tools are: the HTML a plain
+    GET returns is an empty shell, and the content only exists once the app has
+    fetched it with the session this profile holds.
+    """
+    binary = find_browser()
+    if not binary:
+        return Fetched(reason=(
+            "no Chrome, Chromium, Edge or Brave was found on this machine, so a "
+            "link behind a login cannot be opened here. Install one, or set "
+            f"{BINARY_ENV} to its path."))
+    if not profile_dir().exists():
+        return Fetched(reason=(
+            "the SDK's browser profile does not exist yet — nothing has been "
+            "signed in to. Run `agentos browser login <url>`, sign in, close the "
+            "window, and this link becomes readable."))
+    pid = busy_pid()
+    if pid is not None:
+        return Fetched(reason=(
+            f"the SDK's browser profile is open in another window (pid {pid}). "
+            "Close the window `agentos browser login` opened and try again."))
+
+    # `user_agent` shells out for the version. Cached, but the first call per
+    # binary is a subprocess — off the loop, or one read stalls every other
+    # coroutine in the process for as long as the browser takes to answer.
+    agent = await asyncio.to_thread(user_agent)
+    cmd = [binary, "--headless=new", "--disable-gpu", *_base_args(),
+           f"--user-agent={agent}",
+           f"--virtual-time-budget={_VIRTUAL_TIME_MS}",
+           "--dump-dom", url]
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE)
+    except OSError as exc:
+        return Fetched(reason=f"could not start {Path(binary).name} — {exc}")
+    try:
+        out, err = await asyncio.wait_for(proc.communicate(), timeout=timeout)
+    except asyncio.TimeoutError:
+        proc.kill()
+        # Reap it. Without the wait the transport is still open when the loop
+        # closes, which surfaces as a "Event loop is closed" warning from
+        # somewhere entirely unrelated to the browser.
+        with suppress(Exception):
+            # BOUNDED. A killed process whose orphaned child still holds the
+            # pipes never reports exit, and an unbounded wait here would hang the
+            # very call the timeout above exists to bound.
+            await asyncio.wait_for(proc.wait(), timeout=_REAP_TIMEOUT_S)
+        return Fetched(reason=f"timed out rendering in the browser after {int(timeout)}s.")
+
+    html = out.decode(errors="replace").strip()
+    if not html:
+        detail = err.decode(errors="replace").strip().splitlines()
+        tail = detail[-1][:200] if detail else f"exit {proc.returncode}"
+        return Fetched(reason=f"was opened in the browser but rendered nothing — {tail}")
+    return Fetched(html=html)
+
+
+# ── Signing in ────────────────────────────────────────────────────────────────
+
+def _load_sites() -> dict:
+    try:
+        data = json.loads(sites_file().read_text(encoding="utf-8"))
+    except Exception:  # noqa: BLE001 — absent until the first login
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def record_login(url: str) -> str:
+    """Note that a login window was opened for this URL's host. Returns the host."""
+    host = (urlparse(url).hostname or "").lower()
+    if not host:
+        return ""
+    sites = _load_sites()
+    sites[host] = datetime.now(timezone.utc).isoformat(timespec="seconds")
+    try:
+        sites_file().parent.mkdir(parents=True, exist_ok=True)
+        sites_file().write_text(json.dumps(sites, indent=2, sort_keys=True), encoding="utf-8")
+    except OSError as exc:
+        logger.warning("browser_profile.sites_write_failed: %s", exc)
+    return host
+
+
+def logged_in_hosts() -> dict[str, str]:
+    """``{host: when the login window was opened}`` — what we were told, not proof.
+
+    A session can expire, and a person can open the window and never sign in. So
+    this is a record of intent; `agentos report check <url>` is what actually
+    answers whether a host is readable right now.
+    """
+    return dict(sorted(_load_sites().items()))
+
+
+def open_login(url: str) -> tuple[bool, str]:
+    """Open a VISIBLE window on the SDK's profile at ``url``. ``(ok, message)``.
+
+    Returns as soon as the browser is launched — the point is for a person to
+    take it from there, and waiting for them to finish typing a password is not
+    this function's business.
+    """
+    binary = find_browser()
+    if not binary:
+        return False, ("no Chrome, Chromium, Edge or Brave found. Install one, or "
+                       f"set {BINARY_ENV} to its path.")
+    pid = busy_pid()
+    if pid is not None:
+        return False, (f"a window on this profile is already open (pid {pid}). Use it, "
+                       "or close it and run this again.")
+    try:
+        profile_dir().mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        return False, f"cannot create {profile_dir()} — {exc}"
+
+    cmd = [binary, *_base_args(), "--new-window", url]
+    try:
+        subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                         start_new_session=True)
+    except OSError as exc:
+        return False, f"could not start {Path(binary).name} — {exc}"
+    host = record_login(url)
+    return True, host
+
+
+def forget() -> tuple[bool, str]:
+    """Delete the profile — every session in it. ``(ok, message)``."""
+    target = profile_dir()
+    if not target.exists():
+        return True, f"nothing to remove: {target} does not exist."
+    pid = busy_pid()
+    if pid is not None:
+        return False, (f"a window on this profile is open (pid {pid}). Close it first, "
+                       "or the deletion leaves a half-written profile behind.")
+    try:
+        shutil.rmtree(target)
+        sites_file().unlink(missing_ok=True)
+    except OSError as exc:
+        return False, f"could not remove {target} — {exc}"
+    return True, f"removed {target} and every session in it."
+
+
+__all__ = [
+    "BINARY_ENV", "Fetched", "PROFILE_ENV", "busy_pid", "fetch_dom", "find_browser",
+    "forget", "is_available", "logged_in_hosts", "open_login", "profile_dir",
+    "record_login", "sites_file", "user_agent",
+]

{devops_bot_sdk-1.6.28 → devops_bot_sdk-1.6.32}/sdk/cli.py

@@ -143,12 +143,16 @@ def main() -> None:
         _report_command(rest)
         return
 
+    if noun == "browser":
+        _browser_command(rest)
+        return
+
     _print_usage()
     sys.exit(1)
 
 
 def _print_usage() -> None:
-    print("usage: agentos <configure|chat|agent|integration|default-agents|agentd|github|report> ...")
+    print("usage: agentos <configure|chat|agent|integration|default-agents|agentd|github|report|browser> ...")
     print()
     print("  agentos configure [--rotate]")
     print("  agentos chat [--product-id ID] [--pv-id ID] [--no-autorun]   # requirements → ticket")
@@ -159,6 +163,7 @@ def _print_usage() -> None:
     print("  agentos agentd <start [--foreground]|status>")
     print("  agentos github <ingest [--days N]|status>            # PR ingestion; --days N backfills N days")
     print("  agentos report <submit|list|show ID>                 # report work Jira/GitHub never saw")
+    print("  agentos browser <login URL|status|logout>            # sign in once; private links become readable")
 
 
 # ── agent ────────────────────────────────────────────────────────────────
@@ -732,6 +737,7 @@ def _report_usage() -> None:
     print("       agentos report list [--limit N]")
     print("       agentos report show <ID>")
     print("       agentos report formats                              # what a proof can be")
+    print("       agentos report check <URL>                          # can this box open it?")
     print()
     print("  Report work that never reached Jira or GitHub, attach proofs, and have the")
     print("  submission scored against them. It then appears in your daily and overall")
@@ -741,6 +747,11 @@ def _report_usage() -> None:
     print("  --text     the report body; --file reads it from a file instead")
     print("  --proof    repeatable — a local file path OR an http(s) URL")
     print("  --no-wait  submit and exit without waiting for the verdict")
+    print()
+    print("  A proof URL is read HERE, with your own credentials, before it is submitted —")
+    print("  a private PR or an internal page the backend could only 404 on. `check` shows")
+    print("  which route opens a link (gh/az token, a host token, or your signed-in")
+    print("  browser) without submitting anything.")
 
 
 def _report_flag(args: list[str], name: str) -> list[str]:
@@ -758,6 +769,122 @@ def _report_flag(args: list[str], name: str) -> list[str]:
     return out
 
 
+def _browser_usage() -> None:
+    print("usage: agentos browser login <URL>       # sign in once; the session is kept")
+    print("       agentos browser status            # what this profile is signed in to")
+    print("       agentos browser logout [--yes]    # delete the profile and every session")
+    print()
+    print("  A private link is only evidence if something here can open it. Tokens cover")
+    print("  GitHub and Microsoft; everything else — Jira, Confluence, Notion, an internal")
+    print("  dashboard — is covered by a browser that is signed in.")
+    print()
+    print("  That browser is NOT your everyday Chrome profile: Chrome refuses to be driven")
+    print("  while using it, and copying it would be cookie theft by another name. The SDK")
+    print("  keeps its own profile instead, at ~/.agentos/browser-profile, holding only the")
+    print("  sessions you deliberately sign in to here. `logout` deletes all of it.")
+    print()
+    print("  login opens a normal window. Sign in the way you normally would — password,")
+    print("  SSO, MFA, all of it — then close the window. Later reads run headless against")
+    print("  the same profile, so they are signed in too.")
+
+
+def _browser_command(args: list[str]) -> None:
+    """``agentos browser login|status|logout`` — the signed-in half of link access."""
+    from sdk import browser_profile as bp
+
+    verb = args[0] if args else None
+    rest = args[1:]
+
+    if verb == "login" and rest and not rest[0].startswith("-"):
+        url = rest[0]
+        if not (url.startswith("http://") or url.startswith("https://")):
+            print(f"error: not an http(s) URL: {url}")
+            sys.exit(1)
+        ok, message = bp.open_login(url)
+        if not ok:
+            print(f"error: {message}")
+            sys.exit(1)
+        print(f"opened a browser window on the SDK's profile at {url}")
+        print(f"profile : {bp.profile_dir()}")
+        print()
+        print("  1. sign in the way you normally would (password, SSO, MFA — all of it)")
+        print("  2. close the window when the page you want is visible")
+        print(f"  3. check it worked:  agentos report check {url}")
+        print()
+        print("  Tick 'remember me' / 'stay signed in' where the site offers it — a session")
+        print("  cookie with no expiry is dropped when the browser closes, by design.")
+        return
+
+    if verb == "status":
+        binary = bp.find_browser()
+        print(f"browser : {binary or 'NONE FOUND — install Chrome, Chromium, Edge or Brave'}")
+        print(f"profile : {bp.profile_dir()}"
+              f"{'' if bp.profile_dir().exists() else '  (not created yet)'}")
+        pid = bp.busy_pid()
+        if pid is not None:
+            print(f"in use  : yes — a window is open (pid {pid}); headless reads will fail")
+        hosts = bp.logged_in_hosts()
+        if not hosts:
+            print("signed in to: nothing yet — `agentos browser login <url>`")
+        else:
+            print("signed in to:")
+            for host, when in hosts.items():
+                print(f"  {host:<40} (window opened {when})")
+            print()
+            print("  A session can expire, and opening a window is not proof of signing in.")
+            print("  `agentos report check <url>` is what actually answers 'can I read it'.")
+        return
+
+    if verb == "logout":
+        if "--yes" not in rest:
+            print(f"This deletes {bp.profile_dir()} and every session signed in to it.")
+            print("Re-run with --yes to confirm:  agentos browser logout --yes")
+            sys.exit(1)
+        ok, message = bp.forget()
+        print(message if ok else f"error: {message}")
+        sys.exit(0 if ok else 1)
+
+    _browser_usage()
+    sys.exit(1)
+
+
+def _report_check(url: str) -> None:
+    """``agentos report check <URL>`` — can this machine open that link?
+
+    The diagnostic for the whole point of `sdk.url_access`: a proof link is only
+    evidence if something here can read it, and when one comes back unverifiable
+    the operator needs to know WHICH door was shut — no `gh` login, a browser
+    signed out, a host nobody configured a token for — without filing a report to
+    find out. Prints the winning route and a short excerpt, or the reason.
+    """
+    import asyncio
+
+    from sdk import url_access
+
+    res = asyncio.run(url_access.resolve_url(url))
+    print(f"url     : {url}")
+    print(f"tried   : {' -> '.join(res.attempts) or 'nothing'}")
+    if res.ok:
+        excerpt = res.text.strip().splitlines()
+        print(f"readable: yes, via {res.via} ({len(res.text)} chars)")
+        print("excerpt :")
+        for line in excerpt[:8]:
+            print(f"  {line[:110]}")
+        if len(excerpt) > 8:
+            print(f"  … {len(excerpt) - 8} more line(s)")
+        return
+    print("readable: no")
+    print(f"reason  : it {res.reason}")
+    print()
+    print("  Fixes, in the order they usually work:")
+    print("    · `gh auth login`            — private GitHub PRs and issues")
+    print("    · `az login`                 — Outlook/SharePoint via Microsoft Graph")
+    print(f"    · `agentos browser login {url}`  — anything else: sign in once, in a")
+    print("      browser profile the SDK keeps, and every later read is signed in too")
+    print(f"    · add a token for the host to {url_access.AUTH_FILE}")
+    sys.exit(1)
+
+
 def _report_command(args: list[str]) -> None:
     """``agentos report submit|list|show`` — the CLI half of self-reporting.
 
@@ -785,6 +912,9 @@ def _report_command(args: list[str]) -> None:
         if verb == "formats":
             _report_formats()
             return
+        if verb == "check" and rest and not rest[0].startswith("-"):
+            _report_check(rest[0])
+            return
     except TokenNotConfigured as exc:
         # The same failure every other verb gives on an unconfigured machine —
         # `sdk.config` composes a cause-specific message; we only add the prefix.
@@ -899,8 +1029,20 @@ def _report_formats() -> None:
         print("  ffmpeg is NOT installed — a video proof is recorded and described, but")
         print("  its content cannot be inspected. Install ffmpeg to change that.")
     print("  Audio cannot be transcribed locally; it is recorded and described.")
-    print("  URL proofs are fetched here. A GitHub PR or issue is read through the API")
-    print("  with your linked token, so proofs in private repos are readable.")
+    print()
+    print("  Any other file type is still ACCEPTED — it is attached, named and sized,")
+    print("  and scored as evidence that exists but could not be read. Nothing is")
+    print("  refused for its type; only for size or count.")
+    print()
+    from sdk.self_report import MAX_PROOFS, proof_max_mb
+    print(f"  Limits: {proof_max_mb()} MB per proof (AGENTOS_PROOF_MAX_MB), "
+          f"{MAX_PROOFS} proofs per submission.")
+    print()
+    print("  URL proofs are read HERE, with your credentials — a host token, your `gh`")
+    print("  or `az` login, or a browser profile you signed in to once")
+    print("  (`agentos browser login <url>`). `agentos report check <url>` says which.")
+    print("  Media AT a URL is not downloaded as media — attach it as a file to have")
+    print("  it read.")
 
 
 def _report_list(limit: int) -> None: