pythinker-code 2.0.0__py3-none-any.whl

pythinker_code/cli/__main__.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import sys
+
+from pythinker_code.cli import cli
+
+if __name__ == "__main__":
+    from pythinker_code.telemetry.crash import install_crash_handlers, set_phase
+    from pythinker_code.utils.proxy import normalize_proxy_env
+
+    # Same entry treatment as pythinker_code.__main__: install excepthook before
+    # anything else so startup-phase crashes in subcommand subprocesses
+    # (background-task-worker, __web-worker, acp via toad) are captured.
+    install_crash_handlers()
+    normalize_proxy_env()
+    try:
+        sys.exit(cli())
+    finally:
+        set_phase("shutdown")

pythinker_code/cli/_lazy_group.py

@@ -0,0 +1,238 @@
+# pyright: reportAttributeAccessIssue=false, reportMissingParameterType=false, reportPrivateImportUsage=false, reportPrivateUsage=false, reportUnknownArgumentType=false, reportUnknownMemberType=false, reportUnknownParameterType=false, reportUnknownVariableType=false, reportUntypedBaseClass=false
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any, cast
+
+import click
+import typer
+from click.core import HelpFormatter
+from typer.main import get_command
+
+
+class LazySubcommandGroup(typer.core.TyperGroup):
+    """Load heavyweight subcommands only when they are actually invoked."""
+
+    lazy_subcommands: dict[str, tuple[str, str, str]] = {
+        "info": ("pythinker_code.cli.info", "cli", "Show version and protocol information."),
+        "export": ("pythinker_code.cli.export", "cli", "Export session data."),
+        "mcp": ("pythinker_code.cli.mcp", "cli", "Manage MCP server configurations."),
+        "plugin": ("pythinker_code.cli.plugin", "cli", "Manage plugins."),
+        "vis": ("pythinker_code.cli.vis", "cli", "Run Pythinker Agent Tracing Visualizer."),
+        "web": ("pythinker_code.cli.web", "cli", "Run Pythinker CLI web interface."),
+    }
+    lazy_command_order: tuple[str, ...] = (
+        "info",
+        "export",
+        "mcp",
+        "plugin",
+        "vis",
+        "web",
+    )
+
+    # Click options that support optional values.  When the flag is present
+    # without a following argument the parser returns the mapped *flag_value*
+    # instead of raising "requires an argument".
+    _optional_value_options: dict[str, str] = {
+        "session_id": "",  # --session / --resume without value → picker mode
+    }
+
+    def make_context(
+        self, info_name: str | None, args: list[str], parent: click.Context | None = None, **extra
+    ) -> click.Context:
+        for param in self.params:
+            if isinstance(param, click.Option) and param.name in self._optional_value_options:
+                param._flag_needs_value = True
+                param.flag_value = self._optional_value_options[param.name]
+        return super().make_context(info_name, args, parent=parent, **extra)
+
+    def list_commands(self, ctx: click.Context) -> list[str]:
+        commands = list(super().list_commands(ctx))
+        for name in self.lazy_command_order:
+            if name not in commands:
+                commands.append(name)
+        return commands
+
+    def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
+        command = super().get_command(ctx, cmd_name)
+        if command is not None:
+            return command
+
+        lazy_spec = self.lazy_subcommands.get(cmd_name)
+        if lazy_spec is None:
+            return None
+
+        module_name, attribute_name, _ = lazy_spec
+        command = get_command(getattr(import_module(module_name), attribute_name))
+        command.name = cmd_name
+        self.commands[cmd_name] = command
+        return command
+
+    def format_help(self, ctx: click.Context, formatter: HelpFormatter) -> None:
+        if not typer.core.HAS_RICH or self.rich_markup_mode is None:
+            return super().format_help(ctx, formatter)
+
+        from typer import rich_utils
+
+        rich_utils_any = cast(Any, rich_utils)
+        console = rich_utils_any._get_rich_console()
+        console.print(
+            rich_utils_any.Padding(
+                rich_utils_any.highlighter(self.get_usage(ctx)),
+                1,
+            ),
+            style=rich_utils_any.STYLE_USAGE_COMMAND,
+        )
+
+        if self.help:
+            console.print(
+                rich_utils_any.Padding(
+                    rich_utils_any.Align(
+                        rich_utils_any._get_help_text(
+                            obj=self,
+                            markup_mode=self.rich_markup_mode,
+                        ),
+                        pad=False,
+                    ),
+                    (0, 1, 1, 1),
+                )
+            )
+
+        panel_to_arguments: dict[str, list[click.Argument]] = {}
+        panel_to_options: dict[str, list[click.Option]] = {}
+        for param in self.get_params(ctx):
+            if getattr(param, "hidden", False):
+                continue
+            if isinstance(param, click.Argument):
+                panel_name = (
+                    getattr(param, rich_utils_any._RICH_HELP_PANEL_NAME, None)
+                    or rich_utils_any.ARGUMENTS_PANEL_TITLE
+                )
+                panel_to_arguments.setdefault(panel_name, []).append(param)
+            elif isinstance(param, click.Option):
+                panel_name = (
+                    getattr(param, rich_utils_any._RICH_HELP_PANEL_NAME, None)
+                    or rich_utils_any.OPTIONS_PANEL_TITLE
+                )
+                panel_to_options.setdefault(panel_name, []).append(param)
+
+        default_arguments = panel_to_arguments.get(rich_utils_any.ARGUMENTS_PANEL_TITLE, [])
+        rich_utils_any._print_options_panel(
+            name=rich_utils_any.ARGUMENTS_PANEL_TITLE,
+            params=default_arguments,
+            ctx=ctx,
+            markup_mode=self.rich_markup_mode,
+            console=console,
+        )
+        for panel_name, arguments in panel_to_arguments.items():
+            if panel_name == rich_utils_any.ARGUMENTS_PANEL_TITLE:
+                continue
+            rich_utils_any._print_options_panel(
+                name=panel_name,
+                params=arguments,
+                ctx=ctx,
+                markup_mode=self.rich_markup_mode,
+                console=console,
+            )
+
+        default_options = panel_to_options.get(rich_utils_any.OPTIONS_PANEL_TITLE, [])
+        rich_utils_any._print_options_panel(
+            name=rich_utils_any.OPTIONS_PANEL_TITLE,
+            params=default_options,
+            ctx=ctx,
+            markup_mode=self.rich_markup_mode,
+            console=console,
+        )
+        for panel_name, options in panel_to_options.items():
+            if panel_name == rich_utils_any.OPTIONS_PANEL_TITLE:
+                continue
+            rich_utils_any._print_options_panel(
+                name=panel_name,
+                params=options,
+                ctx=ctx,
+                markup_mode=self.rich_markup_mode,
+                console=console,
+            )
+
+        panel_to_commands: dict[str, list[click.Command]] = {}
+        for command_name in self.list_commands(ctx):
+            command = self.commands.get(command_name)
+            if command is None:
+                lazy_spec = self.lazy_subcommands.get(command_name)
+                if lazy_spec is None:
+                    continue
+                command = click.Command(command_name, help=lazy_spec[2])
+            if command.hidden:
+                continue
+            panel_name = (
+                getattr(command, rich_utils_any._RICH_HELP_PANEL_NAME, None)
+                or rich_utils_any.COMMANDS_PANEL_TITLE
+            )
+            panel_to_commands.setdefault(panel_name, []).append(command)
+
+        max_cmd_len = max(
+            (
+                len(command.name or "")
+                for commands in panel_to_commands.values()
+                for command in commands
+            ),
+            default=0,
+        )
+        default_commands = panel_to_commands.get(rich_utils_any.COMMANDS_PANEL_TITLE, [])
+        rich_utils_any._print_commands_panel(
+            name=rich_utils_any.COMMANDS_PANEL_TITLE,
+            commands=default_commands,
+            markup_mode=self.rich_markup_mode,
+            console=console,
+            cmd_len=max_cmd_len,
+        )
+        for panel_name, commands in panel_to_commands.items():
+            if panel_name == rich_utils_any.COMMANDS_PANEL_TITLE:
+                continue
+            rich_utils_any._print_commands_panel(
+                name=panel_name,
+                commands=commands,
+                markup_mode=self.rich_markup_mode,
+                console=console,
+                cmd_len=max_cmd_len,
+            )
+
+        if self.epilog:
+            lines = self.epilog.split("\n\n")
+            epilogue = "\n".join(x.replace("\n", " ").strip() for x in lines)
+            epilogue_text = rich_utils_any._make_rich_text(
+                text=epilogue,
+                markup_mode=self.rich_markup_mode,
+            )
+            console.print(rich_utils_any.Padding(rich_utils_any.Align(epilogue_text, pad=False), 1))
+
+    def format_commands(self, ctx: click.Context, formatter: HelpFormatter) -> None:
+        entries: list[tuple[str, str | None]] = []
+        for subcommand in self.list_commands(ctx):
+            command = self.commands.get(subcommand)
+            if command is not None:
+                if command.hidden:
+                    continue
+                entries.append((subcommand, None))
+                continue
+
+            lazy_spec = self.lazy_subcommands.get(subcommand)
+            if lazy_spec is None:
+                continue
+            entries.append((subcommand, lazy_spec[2]))
+
+        if not entries:
+            return
+
+        limit = formatter.width - 6 - max(len(name) for name, _ in entries)
+        rows: list[tuple[str, str]] = []
+        for subcommand, short_help in entries:
+            command = self.commands.get(subcommand)
+            if command is not None:
+                rows.append((subcommand, command.get_short_help_str(limit)))
+                continue
+            rows.append((subcommand, short_help or ""))
+
+        if rows:
+            with formatter.section("Commands"):
+                formatter.write_dl(rows)

pythinker_code/cli/export.py

@@ -0,0 +1,322 @@
+"""Export command for packaging session data."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import io
+import json
+import platform
+import time
+import zipfile
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Annotated
+
+import typer
+from pythinker_host.path import HostPath
+
+from pythinker_code.wire.file import WireFileMetadata, parse_wire_file_line
+from pythinker_code.wire.types import TurnBegin
+
+if TYPE_CHECKING:
+    from pythinker_code.session import Session
+
+# Include global log files whose last modification is within this window.
+_LOG_RETENTION_SECONDS = 2 * 24 * 60 * 60  # 2 days
+# Maximum total size of log files to bundle in an export archive.
+_MAX_LOG_BYTES = 100 * 1024 * 1024  # 100 MB
+
+cli = typer.Typer(help="Export session data.")
+
+
+async def _find_session_in_work_dir(work_dir: HostPath, session_id: str) -> Session | None:
+    from pythinker_code.session import Session
+
+    return await Session.find(work_dir, session_id)
+
+
+async def _load_previous_session(work_dir: HostPath) -> Session | None:
+    from pythinker_code.session import Session
+
+    return await Session.continue_(work_dir)
+
+
+def _resolve_work_dir(ctx: typer.Context) -> HostPath:
+    root_ctx = ctx.find_root()
+    local_work_dir = root_ctx.params.get("local_work_dir")
+    if local_work_dir is None:
+        return HostPath.cwd()
+    return HostPath.unsafe_from_local_path(local_work_dir)
+
+
+def _find_session_by_id(session_id: str, *, work_dir: HostPath | None = None) -> Path | None:
+    """Find a session directory by ID, preferring the current work directory."""
+    if work_dir is not None:
+        session = asyncio.run(_find_session_in_work_dir(work_dir, session_id))
+        if session is not None:
+            return session.dir
+
+    from pythinker_code.share import get_share_dir
+
+    sessions_root = get_share_dir() / "sessions"
+    if not sessions_root.exists():
+        return None
+
+    for work_dir_hash_dir in sessions_root.iterdir():
+        if not work_dir_hash_dir.is_dir():
+            continue
+        candidate = work_dir_hash_dir / session_id
+        if candidate.is_dir():
+            return candidate
+
+    return None
+
+
+def _last_user_message_timestamp(session_dir: Path) -> float | None:
+    wire_file = session_dir / "wire.jsonl"
+    if not wire_file.exists():
+        return None
+
+    last_turn_begin: float | None = None
+    try:
+        with wire_file.open(encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    parsed = parse_wire_file_line(line)
+                except Exception:
+                    continue
+                if isinstance(parsed, WireFileMetadata):
+                    continue
+                if isinstance(parsed.to_wire_message(), TurnBegin):
+                    last_turn_begin = parsed.timestamp
+    except OSError:
+        return None
+
+    return last_turn_begin
+
+
+def _session_time_range(session_dir: Path) -> tuple[float | None, float | None]:
+    """Return (first_timestamp, last_timestamp) from wire.jsonl."""
+    wire_file = session_dir / "wire.jsonl"
+    if not wire_file.exists():
+        return None, None
+
+    first_ts: float | None = None
+    last_ts: float | None = None
+    try:
+        with wire_file.open(encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    parsed = parse_wire_file_line(line)
+                except Exception:
+                    continue
+                if isinstance(parsed, WireFileMetadata):
+                    continue
+                if first_ts is None:
+                    first_ts = parsed.timestamp
+                last_ts = parsed.timestamp
+    except OSError:
+        pass
+    return first_ts, last_ts
+
+
+def _collect_recent_log_files(session_dir: Path) -> list[Path]:
+    """Collect global log files relevant to a session export.
+
+    Includes the union of:
+    1. Files near the session's active period (wire.jsonl timestamps ± 2 days)
+    2. Files near the export time (now ± 2 days)
+    """
+    from pythinker_code.share import get_share_dir
+
+    log_dir = get_share_dir() / "logs"
+    if not log_dir.is_dir():
+        return []
+
+    now = time.time()
+    export_cutoff = now - _LOG_RETENTION_SECONDS
+
+    session_start, session_end = _session_time_range(session_dir)
+    session_cutoff: float | None = None
+    session_upper: float | None = None
+    if session_start is not None:
+        session_cutoff = session_start - _LOG_RETENTION_SECONDS
+        session_upper = (session_end or session_start) + _LOG_RETENTION_SECONDS
+
+    # Collect candidates with (mtime, size, path)
+    candidates: list[tuple[float, int, Path]] = []
+    for f in log_dir.iterdir():
+        if not f.is_file() or not f.name.startswith("pythinker.") or not f.name.endswith(".log"):
+            continue
+        try:
+            st = f.stat()
+            mtime = st.st_mtime
+            size = st.st_size
+        except OSError:
+            continue
+
+        # Group 2: near export time
+        if mtime >= export_cutoff:
+            candidates.append((mtime, size, f))
+            continue
+
+        # Group 1: near session active period
+        if (
+            session_cutoff is not None
+            and session_upper is not None
+            and mtime >= session_cutoff
+            and mtime <= session_upper
+        ):
+            candidates.append((mtime, size, f))
+
+    # Prioritize files closest to session_end (most diagnostic value),
+    # falling back to recency when session time is unavailable.
+    anchor = session_end or session_start or now
+    candidates.sort(key=lambda item: abs(item[0] - anchor))
+
+    # Apply size cap — keep highest-priority files first
+    result: list[tuple[float, Path]] = []
+    total_size = 0
+    for mtime, size, path in candidates:
+        if total_size + size > _MAX_LOG_BYTES:
+            break
+        result.append((mtime, path))
+        total_size += size
+
+    result.sort(key=lambda item: item[0])
+    return [path for _, path in result]
+
+
+def _build_manifest(session_id: str, session_dir: Path) -> dict[str, str | None]:
+    """Build a manifest dict with system and session diagnostics.
+
+    Best-effort: never raises — returns a minimal manifest on failure.
+    """
+    manifest: dict[str, str | None] = {"session_id": session_id}
+    try:
+        from pythinker_code.constant import get_version
+
+        manifest["exported_at"] = datetime.now(UTC).isoformat()
+        manifest["pythinker_code_version"] = get_version()
+        manifest["python_version"] = platform.python_version()
+        manifest["os"] = f"{platform.system()} {platform.release()}"
+        manifest["platform"] = platform.machine()
+
+        first_ts, last_ts = _session_time_range(session_dir)
+        if first_ts is not None:
+            manifest["session_first_activity"] = datetime.fromtimestamp(first_ts, UTC).isoformat()
+        if last_ts is not None:
+            manifest["session_last_activity"] = datetime.fromtimestamp(last_ts, UTC).isoformat()
+    except Exception:
+        pass
+    return manifest
+
+
+def _format_message_timestamp(timestamp: float | None) -> str:
+    if timestamp is None:
+        return "(no user message)"
+    return datetime.fromtimestamp(timestamp, UTC).strftime("%Y-%m-%d %H:%M:%S UTC")
+
+
+def _confirm_previous_session(session: Session) -> bool:
+    last_user_message = _format_message_timestamp(_last_user_message_timestamp(session.dir))
+
+    typer.echo("About to export the previous session for this working directory:")
+    typer.echo()
+    typer.echo(f"Work dir: {session.work_dir}")
+    typer.echo(f"Session ID: {session.id}")
+    typer.echo(f"Title: {session.title}")
+    typer.echo(f"Last user message: {last_user_message}")
+    typer.echo()
+    return typer.confirm("Export this session?", default=False)
+
+
+@cli.command(name="export")
+def export(
+    ctx: typer.Context,
+    session_id: Annotated[
+        str | None,
+        typer.Argument(help="Session ID to export. Defaults to the previous session."),
+    ] = None,
+    output: Annotated[
+        Path | None,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Output ZIP file path. Default: session-{id}.zip in current directory.",
+        ),
+    ] = None,
+    yes: Annotated[
+        bool,
+        typer.Option(
+            "--yes",
+            "-y",
+            help="Skip confirmation when exporting the previous session by default.",
+        ),
+    ] = False,
+) -> None:
+    """Export a session as a ZIP archive."""
+    work_dir = _resolve_work_dir(ctx)
+
+    if session_id is None:
+        session = asyncio.run(_load_previous_session(work_dir))
+        if session is None:
+            typer.echo("Error: no previous session found for the working directory.", err=True)
+            raise typer.Exit(code=1)
+        if not yes and not _confirm_previous_session(session):
+            typer.echo("Export cancelled.")
+            return
+        session_id = session.id
+        session_dir = session.dir
+    else:
+        session_dir = _find_session_by_id(session_id, work_dir=work_dir)
+        if session_dir is None:
+            typer.echo(f"Error: session '{session_id}' not found.", err=True)
+            raise typer.Exit(code=1)
+
+    # Collect all files in the session directory (including subagents/ and tasks/)
+    files = sorted(f for f in session_dir.rglob("*") if f.is_file())
+    if not files:
+        typer.echo(f"Error: session '{session_id}' has no files.", err=True)
+        raise typer.Exit(code=1)
+
+    # Determine output path
+    if output is None:
+        output = Path.cwd() / f"session-{session_id}.zip"
+
+    # Collect recent global log files for diagnostics
+    log_files = _collect_recent_log_files(session_dir)
+
+    # Build manifest with system diagnostics
+    manifest = _build_manifest(session_id, session_dir)
+
+    # Create ZIP
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+        zf.writestr("manifest.json", json.dumps(manifest, ensure_ascii=False, indent=2))
+        for file_path in files:
+            with contextlib.suppress(OSError):
+                zf.write(file_path, arcname=str(file_path.relative_to(session_dir)))
+        for log_path in log_files:
+            with contextlib.suppress(OSError):
+                zf.write(log_path, arcname=f"logs/{log_path.name}")
+    buf.seek(0)
+
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_bytes(buf.getvalue())
+
+    typer.echo(str(output))
+    if log_files:
+        typer.echo(
+            "\nNote: This archive includes recent diagnostic logs that may contain "
+            "file paths, commands, or configuration from other sessions. "
+            "Please review the contents before sharing.",
+            err=True,
+        )

pythinker_code/cli/info.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import json
+import platform
+from typing import Annotated, TypedDict
+
+import typer
+
+
+class InfoData(TypedDict):
+    pythinker_code_version: str
+    agent_spec_versions: list[str]
+    wire_protocol_version: str
+    python_version: str
+
+
+def _collect_info() -> InfoData:
+    from pythinker_code.agentspec import SUPPORTED_AGENT_SPEC_VERSIONS
+    from pythinker_code.constant import get_version
+    from pythinker_code.wire.protocol import WIRE_PROTOCOL_VERSION
+
+    return {
+        "pythinker_code_version": get_version(),
+        "agent_spec_versions": [str(version) for version in SUPPORTED_AGENT_SPEC_VERSIONS],
+        "wire_protocol_version": WIRE_PROTOCOL_VERSION,
+        "python_version": platform.python_version(),
+    }
+
+
+def _emit_info(json_output: bool) -> None:
+    info = _collect_info()
+    if json_output:
+        typer.echo(json.dumps(info, ensure_ascii=False))
+        return
+
+    agent_versions_text = ", ".join(str(version) for version in info["agent_spec_versions"])
+
+    lines = [
+        f"pythinker-code version: {info['pythinker_code_version']}",
+        f"agent spec versions: {agent_versions_text}",
+        f"wire protocol: {info['wire_protocol_version']}",
+        f"python version: {info['python_version']}",
+    ]
+    for line in lines:
+        typer.echo(line)
+
+
+cli = typer.Typer(help="Show version and protocol information.")
+
+
+@cli.callback(invoke_without_command=True)
+def info(
+    json_output: Annotated[
+        bool,
+        typer.Option(
+            "--json",
+            help="Output information as JSON.",
+        ),
+    ] = False,
+):
+    """Show version and protocol information."""
+    _emit_info(json_output)