reasonwork 0.4.0__py3-none-any.whl

reasonwork_exchange/client.py

@@ -0,0 +1,273 @@
+"""HTTP client for the standalone contributor upload API."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+from reasonwork_exchange.errors import AuthError, ConflictError, ExchangeError, RemoteError, ValidationError
+
+DEFAULT_BASE_URL = "https://ce-staging.collinear.dev"
+
+_MIN_UPLOAD_TIMEOUT_SECONDS = 120
+_UPLOAD_BYTES_PER_SECOND_FLOOR = 256 * 1024  # assume at least a slow-DSL-grade link
+_MAX_PUT_ATTEMPTS = 3
+_PUT_RETRY_BACKOFF_SECONDS = 3.0
+
+
+def _upload_timeout_seconds(byte_size: int) -> int:
+    """Scale the PUT timeout to file size so 100 MB trajectories on slow links don't time out early."""
+    return max(_MIN_UPLOAD_TIMEOUT_SECONDS, int(byte_size / _UPLOAD_BYTES_PER_SECOND_FLOOR))
+
+
+_LOCAL_HOSTS = {"localhost", "127.0.0.1", "::1"}
+
+
+def _require_https(url: str, *, error_code: str, error_cls: type[ExchangeError]) -> None:
+    """Reject a non-HTTPS URL (localhost exempted for local dev/testing).
+
+    Applied both to the configured exchange URL and to any upload URL the
+    server hands back -- a presigned S3 URL is server-supplied, not
+    attacker-controlled, but it's still a URL this process is about to make
+    an outbound request to, so it gets the exact same scheme check rather
+    than being trusted implicitly. error_cls lets each call site keep its
+    existing failure behavior: a bad base_url is a one-time setup mistake
+    (ValidationError, raised once at client construction, same as before this
+    check existed); a bad upload_url shows up per-attempt deep inside the
+    upload retry loop in sync.py, where only RemoteError is handled
+    gracefully -- ValidationError there would crash the whole sync run
+    instead of reporting one item's failure cleanly.
+    """
+    parsed = urllib.parse.urlsplit(url)
+    if not parsed.hostname or (parsed.scheme != "https" and parsed.hostname not in _LOCAL_HOSTS):
+        raise error_cls(
+            "URL must use HTTPS (HTTP is allowed only for localhost)",
+            code=error_code,
+        )
+
+
+class ContributeClient:
+    """Small stdlib-only client so contributor uploads need no new dependency."""
+
+    def __init__(self, token: str, base_url: str | None = None) -> None:
+        """Configure the contributor token and exchange URL."""
+        self.token = token
+        self.base_url = (base_url or os.environ.get("REASONWORK_EXCHANGE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        _require_https(self.base_url, error_code="insecure_contributor_url", error_cls=ValidationError)
+
+    def _json(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        request = urllib.request.Request(
+            f"{self.base_url}{path}",
+            data=json.dumps(payload).encode(),
+            headers={"Authorization": f"Bearer {self.token}", "Content-Type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=30) as response:  # noqa: S310 - fixed HTTPS/user override
+                return dict(json.loads(response.read()))
+        except urllib.error.HTTPError as exc:
+            try:
+                body = json.loads(exc.read())
+            except (json.JSONDecodeError, AttributeError):
+                body = {}
+            message = body.get("error", str(exc))
+            if exc.code == 401:
+                raise AuthError(message, code="invalid_contributor_token") from exc
+            if exc.code in {400, 403}:
+                raise ValidationError(message, code="contributor_validation") from exc
+            if exc.code == 409:
+                raise ConflictError(
+                    message,
+                    code="duplicate_trajectory",
+                    details={"existing_id": body.get("existing_id"), "existing_status": body.get("existing_status")},
+                ) from exc
+            if exc.code == 429:
+                raise RemoteError(
+                    message, code="contributor_rate_limited", hint="wait for prepared uploads to complete, then retry"
+                ) from exc
+            if exc.code == 422:
+                # /complete's own verification failed (partial PUT, S3
+                # eventual-consistency lag) — distinct from a 409 duplicate
+                # conflict; must not be treated as "this file already exists".
+                raise RemoteError(message, code="upload_verification_failed") from exc
+            raise RemoteError(message, code="contributor_api_error", details={"status": exc.code}) from exc
+        except OSError as exc:
+            raise RemoteError(str(exc), code="contributor_api_unreachable") from exc
+
+    def whoami(self) -> dict[str, Any]:
+        """Verify the token and return its contributor identity."""
+        request = urllib.request.Request(
+            f"{self.base_url}/api/contribute/whoami", headers={"Authorization": f"Bearer {self.token}"}, method="GET"
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=30) as response:  # noqa: S310 - fixed HTTPS/user override
+                return dict(json.loads(response.read()))
+        except urllib.error.HTTPError as exc:
+            if exc.code == 401:
+                raise AuthError("invalid or revoked contributor token", code="invalid_contributor_token") from exc
+            raise RemoteError(str(exc), code="contributor_api_error", details={"status": exc.code}) from exc
+        except OSError as exc:
+            raise RemoteError(str(exc), code="contributor_api_unreachable") from exc
+
+    def report_local_rejection(
+        self, path: Path, *, source: str, analysis: dict[str, Any], is_subagent: bool = False
+    ) -> dict[str, Any]:
+        """Report a session the CLI rejected locally for privacy reasons, sending only metadata."""
+        return self._json(
+            "/api/contribute/local-rejections",
+            {
+                "source": source,
+                "client_session_id": analysis.get("session_id"),
+                "is_subagent": is_subagent,
+                "agent_id": analysis.get("agent_id"),
+                "original_filename": path.name,
+                "content_sha256": analysis["content_sha256"],
+                "byte_size": analysis["byte_size"],
+                "line_count": analysis["line_count"],
+                "privacy_risk": analysis["privacy_risk"],
+                "rejection_codes": analysis["rejection_codes"],
+            },
+        )
+
+    def report_local_duplicate(
+        self,
+        path: Path,
+        *,
+        source: str,
+        analysis: dict[str, Any],
+        is_subagent: bool = False,
+        duplicate_of_content_sha256: str,
+    ) -> dict[str, Any]:
+        """Report a session the CLI skipped locally because it's a byte-exact prefix of an already-known file."""
+        return self._json(
+            "/api/contribute/local-duplicates",
+            {
+                "source": source,
+                "client_session_id": analysis.get("session_id"),
+                "is_subagent": is_subagent,
+                "agent_id": analysis.get("agent_id"),
+                "original_filename": path.name,
+                "content_sha256": analysis["content_sha256"],
+                "byte_size": analysis["byte_size"],
+                "line_count": analysis["line_count"],
+                "duplicate_of_content_sha256": duplicate_of_content_sha256,
+            },
+        )
+
+    def upload(
+        self,
+        path: Path,
+        *,
+        source: str,
+        analysis: dict[str, Any],
+        is_subagent: bool = False,
+        supersedes_content_sha256: str | None = None,
+        superseded_byte_size: int | None = None,
+        override_body: bytes | None = None,
+        pii_redacted: bool = False,
+    ) -> dict[str, Any]:
+        """Prepare, PUT, and complete one immutable trajectory.
+
+        `override_body`, when set, is uploaded instead of the file's own bytes — used when
+        `analyzer.redact_trajectory` produced a cleaned copy that must replace the original on
+        the wire. The `content_sha256`/`byte_size` in `analysis` are expected to already
+        describe whatever body is actually being sent.
+        """
+        body = path.read_bytes() if override_body is None else override_body
+        try:
+            prepared = self._json(
+                "/api/contribute/uploads",
+                {
+                    "source": source,
+                    "client_session_id": analysis.get("session_id"),
+                    "is_subagent": is_subagent,
+                    "agent_id": analysis.get("agent_id"),
+                    "original_filename": path.name,
+                    "content_sha256": analysis["content_sha256"],
+                    "byte_size": analysis["byte_size"],
+                    "line_count": analysis["line_count"],
+                    "pii_redacted": pii_redacted,
+                    "client_metrics": {
+                        "uploader": "reasonwork-exchange-cli",
+                        "schema_version": 1,
+                        "deterministic_analysis": analysis,
+                        "rights_reaffirmed": True,
+                    },
+                    "supersedes_content_sha256": supersedes_content_sha256,
+                    "superseded_byte_size": superseded_byte_size,
+                },
+            )
+        except ConflictError as exc:
+            # A previous attempt may have PUT the object to S3 but never reached
+            # /complete (dropped connection, killed process), or an operator
+            # reopened a row an earlier attempt genuinely failed to upload
+            # (status flipped back to "prepared" via the ops dashboard retry).
+            # Resume that same row instead of permanently orphaning it as a
+            # false duplicate.
+            existing_id = exc.details.get("existing_id")
+            existing_status = exc.details.get("existing_status")
+            if existing_id and existing_status == "prepared":
+                return self._resume(existing_id, body)
+            if existing_id and existing_status == "upload_failed":
+                # The row exists but isn't resumable yet: /resume and /complete
+                # both require status == "prepared" server-side, which only an
+                # operator's Retry click restores. Surface this distinctly so
+                # sync.py leaves the path unrecorded (instead of caching it as
+                # a permanent duplicate) and re-checks it on a future sync.
+                raise RemoteError(
+                    "Upload previously failed; awaiting an operator retry before it can resume.",
+                    code="upload_pending_operator_retry",
+                    details=exc.details,
+                ) from exc
+            raise
+        self._put_bytes(str(prepared["upload_url"]), dict(prepared["upload_headers"]), body)
+        return self._json(f"/api/contribute/uploads/{prepared['id']}/complete", {})
+
+    def _resume(self, existing_id: str, body: bytes) -> dict[str, Any]:
+        """Finish a trajectory row that already exists on the server.
+
+        Tries /complete first, which succeeds outright if the earlier attempt's
+        PUT actually landed (dropped connection before /complete). If the bytes
+        genuinely never reached S3 - the case an operator retry reopens - /complete
+        reports upload_verification_failed, so re-request a presigned URL (the
+        original one is long expired) and re-upload before completing again.
+        """
+        try:
+            return self._json(f"/api/contribute/uploads/{existing_id}/complete", {})
+        except RemoteError as exc:
+            if exc.code != "upload_verification_failed":
+                raise
+        reissued = self._json(f"/api/contribute/uploads/{existing_id}/resume", {})
+        self._put_bytes(str(reissued["upload_url"]), dict(reissued["upload_headers"]), body)
+        return self._json(f"/api/contribute/uploads/{existing_id}/complete", {})
+
+    def _put_bytes(self, upload_url: str, upload_headers: dict[str, Any], body: bytes) -> None:
+        # Same scheme check as the exchange URL itself: a presigned S3 URL is
+        # server-supplied rather than attacker-controlled, but nothing else
+        # here re-verifies that before this process opens an outbound
+        # connection to it.
+        _require_https(upload_url, error_code="insecure_upload_url", error_cls=RemoteError)
+        headers = {str(key): str(value) for key, value in upload_headers.items()}
+        timeout = _upload_timeout_seconds(len(body))
+        backoff = _PUT_RETRY_BACKOFF_SECONDS
+        last_error: OSError | None = None
+        for attempt in range(_MAX_PUT_ATTEMPTS):
+            upload_request = urllib.request.Request(upload_url, data=body, headers=headers, method="PUT")
+            try:
+                with urllib.request.urlopen(upload_request, timeout=timeout):  # noqa: S310 - presigned HTTPS URL
+                    return
+            except OSError as exc:
+                # A partial/failed PUT never creates the S3 object, so retrying with the
+                # same presigned URL is safe as long as it's within its expiry.
+                last_error = exc
+                if attempt == _MAX_PUT_ATTEMPTS - 1:
+                    break
+                time.sleep(backoff)
+                backoff *= 2
+        raise RemoteError(str(last_error), code="trajectory_upload_failed") from last_error

reasonwork_exchange/config.py

@@ -0,0 +1,70 @@
+"""Local consent settings for what gets shared to the exchange."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+VALID_SHARING_MODES = frozenset({"all", "ask", "none"})
+
+
+@dataclass(frozen=True)
+class ConsentConfig:
+    """Settings the contributor has agreed to for automatic sharing."""
+
+    sharing_mode: str = "ask"
+    excluded_sources: list[str] = field(default_factory=list)
+    excluded_paths: list[str] = field(default_factory=list)
+
+    def is_excluded(self, source: str, path: Path) -> bool:
+        """Return True if source or path has been opted out of sharing."""
+        if source in self.excluded_sources:
+            return True
+        resolved = str(path.resolve())
+        return any(
+            resolved.startswith(str(Path(prefix).expanduser().resolve()))
+            for prefix in self.excluded_paths
+        )
+
+
+class ConsentConfigStore:
+    """Persist consent settings alongside the contributor auth token."""
+
+    def __init__(self, path: Path | None = None) -> None:
+        """Use an explicit path or default to the contributor config location."""
+        self.path = path or (Path.home() / ".config" / "reasonwork" / "exchange-config.json")
+
+    def read(self) -> ConsentConfig:
+        """Return stored settings, or `ask` defaults if none exist yet."""
+        try:
+            raw = json.loads(self.path.read_text())
+        except (OSError, json.JSONDecodeError):
+            return ConsentConfig()
+        mode = raw.get("sharing_mode", "ask")
+        return ConsentConfig(
+            sharing_mode=mode if mode in VALID_SHARING_MODES else "ask",
+            excluded_sources=list(raw.get("excluded_sources", [])),
+            excluded_paths=list(raw.get("excluded_paths", [])),
+        )
+
+    def write(self, config: ConsentConfig) -> None:
+        """Write settings mode 600, alongside the contributor auth token."""
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        fd = os.open(self.path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, "w") as handle:
+            os.fchmod(handle.fileno(), 0o600)
+            handle.write(
+                json.dumps(
+                    {
+                        "sharing_mode": config.sharing_mode,
+                        "excluded_sources": config.excluded_sources,
+                        "excluded_paths": config.excluded_paths,
+                    },
+                    indent=2,
+                )
+            )
+
+
+__all__ = ["ConsentConfig", "ConsentConfigStore", "VALID_SHARING_MODES"]

reasonwork_exchange/discovery.py

@@ -0,0 +1,59 @@
+"""Discover local agent session files without reading their contents."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class DiscoveredTrajectory:
+    """One local trajectory candidate."""
+
+    source: str
+    path: Path
+    is_subagent: bool = False
+
+
+def discover(home: Path | None = None, limit_per_source: int | None = None) -> list[DiscoveredTrajectory]:
+    """Return Codex, Claude Code, and Cursor CLI JSONL files, newest first.
+
+    When limit_per_source is set, each source's newest N files are kept
+    independently before merging, so a source with sparser or older activity
+    (e.g. Codex or Cursor on a machine used mostly for Claude Code) isn't
+    crowded out of a combined top-N cut.
+    """
+    user_home = home or Path.home()
+    codex_home = Path(os.environ.get("CODEX_HOME", user_home / ".codex"))
+    cursor_home = Path(os.environ.get("CURSOR_HOME", user_home / ".cursor"))
+    by_source = {
+        "codex": [DiscoveredTrajectory("codex", path) for path in (codex_home / "sessions").glob("**/*.jsonl")],
+        "claude_code": [
+            DiscoveredTrajectory("claude_code", path, is_subagent="subagents" in path.parts)
+            for path in (user_home / ".claude" / "projects").glob("**/*.jsonl")
+        ],
+        # cursor-agent (the Cursor CLI) writes one JSONL transcript per session under
+        # <project>/agent-transcripts/<session-id>/; the IDE's own chat history lives
+        # in separate SQLite stores and isn't covered here. Background subagents are
+        # written to a separate top-level ~/.cursor/subagents/ tree (per Cursor's own
+        # docs), not nested under their parent project -- same Claude-Code-compatible
+        # JSONL schema, so the analyzer's existing session/agent-id extraction applies
+        # unchanged once flagged here.
+        "cursor": [
+            DiscoveredTrajectory("cursor", path)
+            for path in (cursor_home / "projects").glob("**/agent-transcripts/**/*.jsonl")
+        ]
+        + [
+            DiscoveredTrajectory("cursor", path, is_subagent=True)
+            for path in (cursor_home / "subagents").glob("**/*.jsonl")
+        ],
+    }
+
+    def newest_first(items: list[DiscoveredTrajectory]) -> list[DiscoveredTrajectory]:
+        return sorted(items, key=lambda item: (-item.path.stat().st_mtime, str(item.path)))
+
+    if limit_per_source is not None:
+        by_source = {source: newest_first(items)[:limit_per_source] for source, items in by_source.items()}
+
+    return newest_first([item for items in by_source.values() for item in items])

reasonwork_exchange/errors.py

@@ -0,0 +1,59 @@
+"""Typed public CLI errors with stable process exit codes."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ExchangeError(Exception):
+    """Base error rendered by the contributor CLI."""
+
+    exit_code: int = 1
+    code: str = "error"
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str | None = None,
+        hint: str | None = None,
+        details: dict[str, Any] | None = None,
+        exit_code: int | None = None,
+    ) -> None:
+        """Create an error with a stable machine code and optional recovery hint."""
+        super().__init__(message)
+        self.message = message
+        if code is not None:
+            self.code = code
+        if exit_code is not None:
+            self.exit_code = exit_code
+        self.hint = hint
+        self.details = details or {}
+
+
+class ValidationError(ExchangeError):
+    """The caller supplied invalid input or an unsafe trajectory."""
+
+    exit_code = 4
+    code = "validation"
+
+
+class ConflictError(ExchangeError):
+    """The trajectory already exists or conflicts with server state."""
+
+    exit_code = 3
+    code = "conflict"
+
+
+class AuthError(ExchangeError):
+    """Contributor authentication is missing or invalid."""
+
+    exit_code = 5
+    code = "auth"
+
+
+class RemoteError(ExchangeError):
+    """The exchange service or upload store could not be reached."""
+
+    exit_code = 6
+    code = "remote"

reasonwork_exchange/output.py

@@ -0,0 +1,73 @@
+"""Stable human and JSON output for the standalone CLI."""
+
+from __future__ import annotations
+
+import functools
+import inspect
+import json
+import sys
+from collections.abc import Callable
+from typing import Annotated, Any
+
+import typer
+from rich.console import Console, RenderableType
+
+from reasonwork_exchange.errors import ExchangeError
+
+console = Console()
+
+
+def emit_success(json_mode: bool, human_lines: list[str], payload: dict[str, Any]) -> int:
+    """Write a successful result in human or stable JSON form."""
+    if json_mode:
+        print(json.dumps({"schema_version": 1, **payload}))
+    else:
+        for line in human_lines:
+            print(line)
+    return 0
+
+
+def emit(json_mode: bool, payload: dict[str, Any], *, human: RenderableType) -> int:
+    """Write a successful Rich result or stable JSON envelope."""
+    if json_mode:
+        print(json.dumps({"schema_version": 1, **payload}))
+    else:
+        console.print(human)
+    return 0
+
+
+def emit_error(json_mode: bool, error: ExchangeError) -> None:
+    """Write an expected error to stderr."""
+    if json_mode:
+        print(
+            json.dumps({"error": error.message, "code": error.code, "hint": error.hint, "details": error.details}),
+            file=sys.stderr,
+        )
+    else:
+        print(f"error: {error.message}", file=sys.stderr)
+        if error.hint:
+            print(f"hint: {error.hint}", file=sys.stderr)
+
+
+def handle_errors(function: Callable[..., int | None]) -> Callable[..., None]:
+    """Render expected errors and propagate command return codes through Typer."""
+    if "json_" not in inspect.signature(function).parameters:
+        name = getattr(function, "__qualname__", repr(function))
+        raise TypeError(f"{name} must declare a json_ option")
+
+    @functools.wraps(function)
+    def wrapper(*args: object, **kwargs: object) -> None:
+        try:
+            return_code = function(*args, **kwargs)
+        except ExchangeError as error:
+            emit_error(bool(kwargs.get("json_", False)), error)
+            raise typer.Exit(error.exit_code) from error
+        except KeyboardInterrupt:
+            raise typer.Exit(1) from None
+        if return_code:
+            raise typer.Exit(return_code)
+
+    return wrapper
+
+
+JsonOpt = Annotated[bool, typer.Option("--json", help="Emit stable JSON on stdout (schema_version: 1).")]