panagent 0.3.0__py3-none-any.whl

panagent/__init__.py

@@ -0,0 +1,30 @@
+"""Move agent conversations between Claude Code, Codex, ChatGPT, Claude and tavya.
+
+    import panagent
+    conversation = panagent.load("https://chatgpt.com/share/...")
+    print(panagent.render(conversation, "markdown").text)
+    panagent.install(conversation, "claude-code").command  # 'cd ... && claude --resume ...'
+"""
+
+__version__ = "0.3.0"
+
+from .api import Installed, install, load, parse, render
+from .errors import AcquisitionError, BrowserRequired, FormatError, PanagentError
+from .model import SCHEMA, new_conversation, validate_conversation
+from .writers import Rendered
+
+__all__ = [
+    "SCHEMA",
+    "AcquisitionError",
+    "BrowserRequired",
+    "FormatError",
+    "Installed",
+    "PanagentError",
+    "Rendered",
+    "install",
+    "load",
+    "new_conversation",
+    "parse",
+    "render",
+    "validate_conversation",
+]

panagent/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

panagent/api.py

@@ -0,0 +1,171 @@
+"""The library interface: load any supported source, render or install it as any target."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from shlex import quote
+from typing import Any
+from uuid import uuid4
+
+from .browser import fetch_share_browser
+from .detect import canonical_format, detect_text, url_format
+from .errors import AcquisitionError, BrowserRequired, PanagentError
+from .model import default_mode, validate_conversation
+from .readers import READERS, read_file
+from .web import WEB_READERS, fetch_share
+from .writers import WRITERS, Rendered
+
+# Shares whose pages may need a real browser (a challenge or a client-rendered app).
+BROWSER_FORMATS = {"chatgpt-share", "claude-share"}
+NATIVE_TARGETS = {"claude-code", "codex"}
+
+
+def parse(
+    text: str,
+    source_format: str | None = None,
+    *,
+    source_uri: str | None = None,
+    conversation: str | None = None,
+) -> dict[str, Any]:
+    """Read a conversation from text in any supported input format (detected when omitted)."""
+    fmt = canonical_format(source_format) if source_format else detect_text(text)
+    reader = READERS.get(fmt) or WEB_READERS.get(fmt)
+    if reader is None:
+        raise PanagentError(f"{fmt} is output-only")
+    return validate_conversation(reader(text, source_uri=source_uri, conversation=conversation))
+
+
+def load(
+    source: str | os.PathLike[str],
+    source_format: str | None = None,
+    *,
+    conversation: str | None = None,
+    timeout: float = 30.0,
+    browser: str = "never",
+    browser_timeout: float = 120.0,
+    cdp_url: str | None = None,
+    browser_profile: str | None = None,
+) -> dict[str, Any]:
+    """Read a conversation from a file or a public share URL.
+
+    browser is "never" (the library default), "auto", "headless" or "headed";
+    it only applies to ChatGPT and Claude shares that plain HTTPS cannot read.
+    """
+    source = os.fspath(source)
+    share = url_format(source) if "://" in source else None
+    if not share:
+        return parse(read_file(Path(source)), source_format, source_uri=source, conversation=conversation)
+    fmt = canonical_format(source_format) if source_format else share
+    if fmt != share:
+        raise PanagentError(f"URL does not match source format {fmt}")
+    reader = WEB_READERS[fmt]
+
+    def through_browser() -> dict[str, Any]:
+        text = fetch_share_browser(source, timeout=browser_timeout, mode=browser, cdp_url=cdp_url, profile=browser_profile)
+        return validate_conversation(reader(text, source_uri=source))
+
+    if fmt in BROWSER_FORMATS and (browser in {"headless", "headed"} or cdp_url):
+        return through_browser()
+    try:
+        return validate_conversation(reader(fetch_share(source, timeout=timeout), source_uri=source))
+    except AcquisitionError as exc:
+        retryable = isinstance(exc, BrowserRequired) or exc.status in {403, 429}
+        if fmt not in BROWSER_FORMATS or browser == "never" or not retryable:
+            raise
+        return through_browser()
+
+
+def render(
+    conv: dict[str, Any],
+    target: str,
+    *,
+    mode: str = "auto",
+    cwd: str | None = None,
+    session_id: str | None = None,
+) -> Rendered:
+    """Write a conversation as target ("ir", "markdown", "claude-code" or "codex").
+
+    mode "auto" gives native targets a guarded context message for web snapshots
+    and a turn-by-turn transcript for agent sessions; IR and Markdown ignore it.
+    """
+    fmt = canonical_format(target)
+    writer = WRITERS.get(fmt)
+    if writer is None:
+        raise PanagentError(f"{fmt} is input-only")
+    validate_conversation(conv)
+    if mode == "auto":
+        mode = default_mode(conv) if fmt in NATIVE_TARGETS else "transcript"
+    if mode not in {"context", "transcript"}:
+        raise PanagentError(f"unknown mode: {mode}")
+    rendered = writer(conv, mode=mode, cwd=cwd, session_id=session_id)
+    rendered.format, rendered.mode = fmt, mode
+    return rendered
+
+
+@dataclass
+class Installed:
+    path: Path
+    session_id: str
+    command: str
+    rendered: Rendered
+
+
+def install(
+    conv: dict[str, Any],
+    target: str,
+    *,
+    cwd: str | os.PathLike[str] | None = None,
+    session_id: str | None = None,
+    mode: str = "auto",
+    home: str | os.PathLike[str] | None = None,
+) -> Installed:
+    """Add a conversation to Claude Code's or Codex's own history as a new session.
+
+    Claude Code finds sessions per project, so cwd (default: the current
+    directory) is where `claude --resume` must run. home overrides the CLI's
+    data directory ($CLAUDE_CONFIG_DIR or ~/.claude; $CODEX_HOME or ~/.codex).
+    An existing session file is never overwritten.
+    """
+    fmt = canonical_format(target)
+    if fmt not in NATIVE_TARGETS:
+        raise PanagentError("only claude-code and codex sessions can be installed")
+    directory = str(Path(cwd or os.getcwd()).expanduser().resolve())
+    # The installed copy is a new session of the target CLI, never the source's identity.
+    session_id = session_id or str(uuid4())
+    rendered = render(conv, fmt, mode=mode, cwd=directory, session_id=session_id)
+    if fmt == "claude-code":
+        root = Path(home or os.environ.get("CLAUDE_CONFIG_DIR") or Path.home() / ".claude").expanduser()
+        path = root / "projects" / re.sub(r"[^A-Za-z0-9]", "-", directory) / f"{session_id}.jsonl"
+        command = f"cd {quote(directory)} && claude --resume {session_id}"
+    else:
+        root = Path(home or os.environ.get("CODEX_HOME") or Path.home() / ".codex").expanduser()
+        started = _utc(rendered.text.split("\n", 1)[0])
+        path = (root / "sessions" / started.strftime("%Y/%m/%d")
+                / f"rollout-{started.strftime('%Y-%m-%dT%H-%M-%S')}-{session_id}.jsonl")
+        command = f"codex resume {session_id}"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    except FileExistsError as exc:
+        raise PanagentError(f"session {session_id} already exists at {path}") from exc
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8", newline="") as handle:
+            handle.write(rendered.text)
+    except BaseException:
+        path.unlink(missing_ok=True)
+        raise
+    return Installed(path, session_id, command, rendered)
+
+
+def _utc(first_record: str) -> datetime:
+    """The session start of a Codex rollout (from its session_meta record), else now."""
+    try:
+        value = json.loads(first_record)["timestamp"]
+        return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(timezone.utc)
+    except (ValueError, KeyError, TypeError, AttributeError):
+        return datetime.now(timezone.utc)

panagent/browser.py

@@ -0,0 +1,210 @@
+"""Optional real-browser acquisition for share pages that resist plain HTTP."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+import time
+from contextlib import ExitStack
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+from .errors import AcquisitionError
+from .web import is_challenge_page
+
+
+CLAUDE_MESSAGE_SELECTOR = (
+    '[data-message-author-role], [data-author-role], '
+    '[data-testid*="user-message"], [data-testid*="human-message"], '
+    '[data-testid*="assistant-message"], [data-testid*="ai-message"]'
+)
+
+
+def fetch_share_browser(
+    url: str,
+    *,
+    timeout: float = 120.0,
+    mode: str = "auto",
+    cdp_url: str | None = None,
+    profile: str | None = None,
+) -> str:
+    """Render a share in Chromium and return structured JSON or final HTML.
+
+    Playwright is deliberately optional. A CDP connection is the safest path for
+    an already-open, user-controlled Chrome because authentication and challenge
+    cookies remain in that browser. Otherwise a dedicated persistent profile can
+    be used with a headed browser so the user can complete a challenge directly.
+    """
+
+    if cdp_url and urlparse(cdp_url).hostname not in {"127.0.0.1", "::1", "localhost"}:
+        raise AcquisitionError("--cdp-url is restricted to loopback because Chrome debugging grants full browser control")
+
+    try:
+        from playwright.sync_api import Error as PlaywrightError
+        from playwright.sync_api import TimeoutError as PlaywrightTimeoutError
+        from playwright.sync_api import sync_playwright
+    except ImportError as exc:
+        raise AcquisitionError(
+            "browser acquisition requires the optional Playwright support. Install it with "
+            "`python -m pip install 'panagent[browser]'`, then run `playwright install chromium`, "
+            "or pass --cdp-url for an existing Chrome debugging endpoint."
+        ) from exc
+
+    deadline = time.monotonic() + max(timeout, 1.0)
+    captured_json: list[str] = []
+    browser: Any = None
+    context: Any = None
+    page: Any = None
+    owns_context = False
+    try:
+        # ExitStack closes the tab/context before Playwright disconnects. This
+        # matters for CDP: disconnecting first would leave our tab in the user's
+        # already-running browser.
+        with sync_playwright() as playwright, ExitStack() as cleanup:
+            if cdp_url:
+                try:
+                    browser = playwright.chromium.connect_over_cdp(cdp_url)
+                except PlaywrightError as exc:
+                    raise AcquisitionError(f"could not connect to Chrome at {cdp_url}: {exc}") from exc
+                had_context = bool(browser.contexts)
+                context = browser.contexts[0] if had_context else browser.new_context()
+                owns_context = not had_context
+            else:
+                headed = _headed(mode)
+                if mode in {"auto", "headed"} and not headed:
+                    raise AcquisitionError(
+                        "Claude requires an interactive browser challenge in this environment. Run from a desktop "
+                        "terminal with --browser headed, or expose an existing Chrome with remote debugging and "
+                        "pass --cdp-url."
+                    )
+                user_data_dir = profile
+                if user_data_dir is None:
+                    temporary_profile = tempfile.TemporaryDirectory(prefix="panagent-browser-")
+                    cleanup.callback(temporary_profile.cleanup)
+                    user_data_dir = temporary_profile.name
+                Path(user_data_dir).expanduser().mkdir(parents=True, exist_ok=True)
+                context = _launch_persistent(playwright, str(Path(user_data_dir).expanduser()), headless=not headed)
+                owns_context = True
+
+            if owns_context:
+                cleanup.callback(_safe_close, context)
+            page = context.new_page()
+            cleanup.callback(_safe_close, page)
+
+            def capture(response: Any) -> None:
+                if "claude.ai" not in url or "json" not in (response.headers.get("content-type") or "").lower():
+                    return
+                try:
+                    body = response.text()
+                except PlaywrightError:
+                    return
+                if "chat_messages" in body or '"messages"' in body and ('"uuid"' in body or '"title"' in body):
+                    captured_json.append(body)
+
+            page.on("response", capture)
+            try:
+                page.goto(url, wait_until="domcontentloaded", timeout=min(timeout, 30.0) * 1000)
+            except PlaywrightTimeoutError:
+                # A challenge or client-rendered app can keep navigation busy. The
+                # polling below inspects the page until the full acquisition timeout.
+                pass
+
+            while time.monotonic() < deadline:
+                if captured_json:
+                    return captured_json[-1]
+                if "claude.ai" in url:
+                    exported = _claude_dom_export(page)
+                    if exported is not None:
+                        return json.dumps(exported, ensure_ascii=False)
+                else:
+                    html = page.content()
+                    if "streamController.enqueue" in html or page.locator("[data-message-author-role]").count() >= 2:
+                        return html
+                if mode == "headless" and not cdp_url and is_challenge_page(page.content(), page.url):
+                    raise AcquisitionError(
+                        "Claude returned a challenge that cannot be completed in a headless browser. "
+                        "Use --browser headed or --cdp-url with a user-controlled Chrome."
+                    )
+                page.wait_for_timeout(500)
+
+            html = page.content()
+            if is_challenge_page(html, page.url):
+                raise AcquisitionError(
+                    "the browser challenge was not completed before the timeout. Complete it in the opened browser "
+                    "and retry with a longer --browser-timeout, or use --cdp-url with that browser."
+                )
+            if "claude.ai" in url:
+                raise AcquisitionError(
+                    "Claude rendered no recognizable conversation messages. Keep the share open until it fully "
+                    "loads, or use the documented browser JSON/HTML export fallback."
+                )
+            return html
+    except PlaywrightError as exc:
+        raise AcquisitionError(
+            f"browser acquisition failed: {exc}. Install a Playwright browser with `playwright install chromium`, "
+            "or pass --cdp-url for an existing Chrome instance."
+        ) from exc
+
+
+def _safe_close(resource: Any) -> None:
+    try:
+        resource.close()
+    except Exception:
+        pass
+
+
+def _headed(mode: str) -> bool:
+    if mode == "headed":
+        return True
+    if mode == "headless":
+        return False
+    if not sys.stdin.isatty():
+        return False
+    if sys.platform.startswith("linux"):
+        return bool(os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY"))
+    return True
+
+
+def _launch_persistent(playwright: Any, profile: str, *, headless: bool) -> Any:
+    errors: list[str] = []
+    for options in ({"channel": "chrome"}, {}):
+        try:
+            return playwright.chromium.launch_persistent_context(profile, headless=headless, **options)
+        except Exception as exc:
+            errors.append(str(exc))
+    raise AcquisitionError(
+        "could not launch Chrome/Chromium. Install Google Chrome or run `playwright install chromium`. "
+        + " | ".join(errors)
+    )
+
+
+def _claude_dom_export(page: Any) -> dict[str, Any] | None:
+    value = page.evaluate(
+        """(selector) => {
+          const all = [...document.querySelectorAll(selector)];
+          const nodes = all.filter((node) => !all.some((other) => other !== node && node.contains(other)));
+          const chat_messages = nodes.map((element, index) => {
+            const testid = (element.getAttribute('data-testid') || '').toLowerCase();
+            const nativeRole = element.getAttribute('data-message-author-role') ||
+              element.getAttribute('data-author-role') ||
+              (testid.includes('user') || testid.includes('human') ? 'human' : 'assistant');
+            return {
+              uuid: element.getAttribute('data-message-id') || element.id || `browser-${index}`,
+              sender: nativeRole === 'user' ? 'human' : nativeRole,
+              text: element.innerText
+            };
+          }).filter((item) => item.text && ['human', 'assistant', 'system'].includes(item.sender));
+          if (chat_messages.length < 2) return null;
+          return {
+            name: document.title.replace(/^Claude\\s*[-–]\\s*/, ''),
+            source_url: location.href,
+            chat_messages
+          };
+        }""",
+        CLAUDE_MESSAGE_SELECTOR,
+    )
+    return value if isinstance(value, dict) else None
+

panagent/cli.py

@@ -0,0 +1,228 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any, Sequence
+from uuid import UUID
+
+from . import __version__
+from .api import NATIVE_TARGETS, install, load, parse, render
+from .detect import FORMAT_ALIASES, canonical_format, detect_text
+from .errors import PanagentError
+from .readers import READERS, read_file
+from .web import WEB_READERS, list_conversations
+from .writers import WRITERS, Rendered
+
+INPUTS = sorted(name for name, fmt in FORMAT_ALIASES.items() if fmt in READERS or fmt in WEB_READERS)
+OUTPUTS = sorted(name for name, fmt in FORMAT_ALIASES.items() if fmt in WRITERS)
+
+
+def _session_id(value: str) -> str:
+    try:
+        return str(UUID(value))
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("session id must be a UUID") from exc
+
+
+def parser() -> argparse.ArgumentParser:
+    result = argparse.ArgumentParser(
+        prog="panagent",
+        description="Move conversations between Claude Code, Codex, ChatGPT, Claude and tavya through a provenance-preserving neutral format.",
+    )
+    result.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = result.add_subparsers(dest="command", required=True)
+
+    convert = subparsers.add_parser("convert", help="convert a conversation or public share")
+    convert.add_argument("source", help="input file, '-' for stdin, or a public share URL")
+    convert.add_argument("--from", dest="source_format", choices=INPUTS, help="source format (default: detect)")
+    convert.add_argument("--to", dest="target_format", required=True, choices=OUTPUTS, help="destination format")
+    destination = convert.add_mutually_exclusive_group()
+    destination.add_argument("-o", "--output", default="-", help="output file (default: stdout)")
+    destination.add_argument(
+        "--install",
+        action="store_true",
+        help="add the result to the destination CLI's own history as a new session and print its resume command",
+    )
+    convert.add_argument("--conversation", help="conversation id or exact title, for exports holding several")
+    convert.add_argument(
+        "--mode",
+        choices=["auto", "context", "transcript"],
+        default="auto",
+        help="native output strategy; auto uses guarded context for web chats and transcript for agent sessions",
+    )
+    convert.add_argument("--cwd", help="working directory recorded in a generated native session (--install: default current)")
+    convert.add_argument(
+        "--session-id",
+        type=_session_id,
+        help="destination native session id (default: preserve a UUID source id; --install: a new id)",
+    )
+    convert.add_argument("--timeout", type=float, default=30.0, help="share request timeout in seconds (default: 30)")
+    convert.add_argument(
+        "--browser",
+        choices=["auto", "never", "headless", "headed"],
+        default="auto",
+        help="browser fallback for challenged ChatGPT/Claude shares (default: auto; Playwright is optional)",
+    )
+    convert.add_argument(
+        "--browser-timeout",
+        type=float,
+        default=120.0,
+        help="seconds to wait for browser rendering or a user-completed challenge (default: 120)",
+    )
+    convert.add_argument("--cdp-url", help="connect to an existing Chrome debugging endpoint, for example http://127.0.0.1:9222")
+    convert.add_argument("--browser-profile", help="dedicated Chrome/Chromium profile directory used by browser acquisition")
+    convert.add_argument("--report", help="write a machine-readable conversion/loss report")
+    convert.add_argument("--quiet", action="store_true", help="do not print warnings or summary to stderr")
+    convert.add_argument("--fail-on-warning", action="store_true", help="return exit status 3 when any warning is emitted")
+    convert.set_defaults(handler=_convert)
+
+    validate = subparsers.add_parser("validate", help="parse and validate an input without converting it")
+    validate.add_argument("source", help="input file or '-' for stdin")
+    validate.add_argument("--from", dest="source_format", choices=INPUTS, help="source format (default: detect)")
+    validate.add_argument("--conversation", help="conversation id or exact title, for exports holding several")
+    validate.add_argument("--quiet", action="store_true")
+    validate.set_defaults(handler=_validate)
+
+    listing = subparsers.add_parser("list", help="list the conversations in a ChatGPT or Claude data export")
+    listing.add_argument("source", help="conversations.json, or '-' for stdin")
+    listing.add_argument("--from", dest="source_format", choices=INPUTS, help="source format (default: detect)")
+    listing.set_defaults(handler=_list)
+    return result
+
+
+def _read_source(source: str) -> str:
+    if source == "-":
+        return sys.stdin.read()
+    if "://" in source:
+        raise PanagentError("this command reads local files or stdin; use convert for a share URL")
+    return read_file(Path(source))
+
+
+def _load(args: argparse.Namespace, *, allow_url: bool) -> dict[str, Any]:
+    if args.source == "-" or not allow_url:
+        return parse(_read_source(args.source), args.source_format, conversation=args.conversation)
+    return load(
+        args.source,
+        args.source_format,
+        conversation=args.conversation,
+        timeout=args.timeout,
+        browser=args.browser,
+        browser_timeout=args.browser_timeout,
+        cdp_url=args.cdp_url,
+        browser_profile=args.browser_profile,
+    )
+
+
+def _convert(args: argparse.Namespace) -> int:
+    conv = _load(args, allow_url=True)
+    options = {"mode": args.mode, "cwd": args.cwd, "session_id": args.session_id}
+    if args.install:
+        if canonical_format(args.target_format) not in NATIVE_TARGETS:
+            raise PanagentError("--install needs --to claude-code or --to codex")
+        installed = install(conv, args.target_format, **options)
+        rendered, destination = installed.rendered, str(installed.path)
+        print(installed.command)
+    else:
+        rendered, destination = render(conv, args.target_format, **options), args.output
+        _write_output(args.output, rendered.text)
+    warnings = [*conv.get("warnings", []), *rendered.warnings]
+    report = _report(conv, rendered, warnings)
+    if args.report:
+        _write_output(args.report, json.dumps(report, ensure_ascii=False, indent=2) + "\n")
+    if not args.quiet:
+        _print_report(report, destination)
+    return 3 if args.fail_on_warning and any(item.get("severity", "warning") != "info" for item in warnings) else 0
+
+
+def _validate(args: argparse.Namespace) -> int:
+    conv = _load(args, allow_url=False)
+    if not args.quiet:
+        print(
+            f"valid {conv['source']['format']}: {len(conv['messages'])} messages, {len(conv.get('warnings', []))} warnings",
+            file=sys.stderr,
+        )
+    return 0
+
+
+def _list(args: argparse.Namespace) -> int:
+    text = _read_source(args.source)
+    fmt = canonical_format(args.source_format) if args.source_format else detect_text(text)
+    if fmt in {"chatgpt-share", "claude-share"} and text.lstrip("\ufeff \t\r\n").startswith(("[", "{")):
+        rows = list_conversations(text, fmt)
+    else:
+        conv = parse(text, fmt)
+        rows = [{"id": conv["id"], "title": conv.get("title") or "", "updated_at": conv.get("updated_at"),
+                 "messages": len(conv["messages"])}]
+    for row in rows:
+        print("\t".join([str(row["id"] or ""), (row["updated_at"] or "")[:10], str(row["messages"]), row["title"]]))
+    return 0
+
+
+def _report(conv: dict[str, Any], rendered: Rendered, warnings: list[dict[str, Any]]) -> dict[str, Any]:
+    blocks: dict[str, int] = {}
+    roles: dict[str, int] = {}
+    for item in conv["messages"]:
+        roles[item["role"]] = roles.get(item["role"], 0) + 1
+        for block in item["content"]:
+            kind = block["type"]
+            blocks[kind] = blocks.get(kind, 0) + 1
+    return {
+        "source_format": conv["source"]["format"],
+        "target_format": rendered.format,
+        "mode": rendered.mode,
+        "conversation_id": conv.get("id"),
+        "messages": len(conv["messages"]),
+        "roles": roles,
+        "content_blocks": blocks,
+        "capabilities": conv.get("capabilities", {}),
+        "warnings": warnings,
+        "output_bytes": len(rendered.text.encode("utf-8")),
+    }
+
+
+def _print_report(report: dict[str, Any], output: str) -> None:
+    destination = "stdout" if output == "-" else output
+    print(
+        f"panagent: {report['source_format']} -> {report['target_format']} ({report['mode']}): "
+        f"{report['messages']} messages written to {destination}",
+        file=sys.stderr,
+    )
+    # Readers warn once per affected record; one line per code is enough on a terminal.
+    grouped: dict[str, list[dict[str, Any]]] = {}
+    for item in report["warnings"]:
+        grouped.setdefault(item.get("code", "warning"), []).append(item)
+    for code, items in grouped.items():
+        count = f" ({len(items)}x)" if len(items) > 1 else ""
+        print(f"panagent: {items[0].get('severity', 'warning')}: {code}{count}: {items[0].get('message', '')}", file=sys.stderr)
+
+
+def _write_output(target: str, content: str) -> None:
+    if target == "-":
+        sys.stdout.write(content)
+        return
+    path = Path(target)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent, text=True)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8", newline="") as handle:
+            handle.write(content)
+        os.replace(temporary, path)
+    except BaseException:
+        try:
+            os.unlink(temporary)
+        except OSError:
+            pass
+        raise
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = parser().parse_args(argv)
+    try:
+        return int(args.handler(args))
+    except (PanagentError, OSError, UnicodeError, ValueError, TypeError, KeyError) as exc:
+        print(f"panagent: error: {exc}", file=sys.stderr)
+        return 2