vidbyte-cli 0.1.0__py3-none-any.whl

vidbyte_cli/commands/setup/doctor.py

@@ -0,0 +1,64 @@
+"""`vidbyte-cli doctor` — checks the CLI environment and credentials.
+
+Diagnosis is read-only: doctor never migrates or repairs, because a user running it to find
+out what is wrong should not have the answer change underneath them. It reports whether a
+credential exists and where it came from, never its value. API identity and repository
+checks arrive with the HTTP platform.
+"""
+
+from __future__ import annotations
+
+import click
+from pydantic import JsonValue
+
+from ...lib.auth.credentials import Credentials
+from ...lib.output import OutputDocument
+from ...lib.runtime.context import ApplicationContext
+
+
+class DoctorCommand:
+    def register(self, parent: click.Group) -> None:
+        @parent.command(name="doctor", help="Diagnose local CLI configuration and credentials")
+        @click.pass_obj
+        def _run(context: ApplicationContext) -> None:
+            self.execute(context)
+
+    def execute(self, context: ApplicationContext) -> None:
+        config = context.resolved_config()
+        store = context.credential_store()
+        credential = context.credential_resolver().resolve(config.profile, config.api_url)
+        keyring_available = store.keyring.available()
+        legacy_present = context.paths().legacy_root.exists()
+        # A credential written by hand rather than by login never crossed the input guard, so
+        # the format is reported: the backend ignores a non-live key, which otherwise looks
+        # exactly like being logged out.
+        live_format = (
+            Credentials.is_live_format(credential.credentials.secret_value())
+            if credential is not None
+            else None
+        )
+        data: dict[str, JsonValue] = {
+            "profile": config.profile,
+            "api_url": config.api_url,
+            "config_path": config.config_path,
+            "credential_present": credential is not None,
+            "credential_source": credential.source.value if credential is not None else None,
+            "credential_live_format": live_format,
+            "keyring_available": keyring_available,
+            "legacy_state_present": legacy_present,
+        }
+        credential_status = (
+            f"present ({credential.source.value})" if credential is not None else "not found"
+        )
+        if live_format is False:
+            credential_status += " - not a live key, the backend will ignore it"
+        human = "\n".join(
+            (
+                f"Profile: {config.profile}",
+                f"API URL: {config.api_url}",
+                f"Credentials: {credential_status}",
+                f"OS keyring: {'available' if keyring_available else 'unavailable'}",
+                f"Legacy state: {'present' if legacy_present else 'not found'}",
+            )
+        )
+        context.output().result(OutputDocument(kind="doctor.local", data=data), human)

vidbyte_cli/commands/setup/prompts/__init__.py

@@ -0,0 +1 @@
+"""Markdown assets used by setup command help."""

vidbyte_cli/commands/setup/prompts/browser.md

@@ -0,0 +1,7 @@
+# `--browser`
+
+## Purpose
+This flag skips the GitHub CLI and opens the public repository page in the default browser instead. Use it when you prefer to click Star yourself, or when the GitHub CLI is logged in to an account you do not want to star from. With this flag, the command never invokes the GitHub CLI, so no GitHub API request is made. The repository URL is printed as well, so it still works on a machine without a browser. The resulting record reports the method as `browser` and the star as unconfirmed.
+
+## Default
+The flag is off by default, which tries the GitHub CLI first and falls back to the browser only when that fails. Leaving it off is the faster path for people who already use the GitHub CLI. Turning it on is the right choice in shared or borrowed environments where the logged-in GitHub account is not your own. The flag takes no value and has no environment-variable equivalent.

vidbyte_cli/commands/setup/prompts/library.py

@@ -0,0 +1,18 @@
+"""Loads caller-facing setup help from packaged Markdown assets."""
+
+from __future__ import annotations
+
+from importlib import resources
+
+
+class SetupHelpLibrary:
+    """Reads each setup help description from its named Markdown asset."""
+
+    def __init__(self) -> None:
+        self._cache: dict[str, str] = {}
+
+    def load(self, name: str) -> str:
+        if name not in self._cache:
+            asset = resources.files(__package__).joinpath(f"{name}.md")
+            self._cache[name] = asset.read_text(encoding="utf-8").strip()
+        return self._cache[name]

vidbyte_cli/commands/setup/prompts/star.md

@@ -0,0 +1,13 @@
+# Star the Vidbyte CLI
+
+## Purpose
+This command stars the public Vidbyte CLI repository on GitHub for the person running it. It exists so a user who finds the CLI useful can show support without leaving the terminal. It never runs on its own: no other command, hint, or error path invokes it. An agent driving this CLI must never run it on a user's behalf, because starring is a personal endorsement and GitHub forbids inauthentic interactions. Run it only when the user has asked to star the project.
+
+## How it stars
+When the GitHub CLI (`gh`) is installed and logged in, the command asks it to star the repository through the GitHub API. The GitHub CLI owns the login, so this package never sees, stores, or prompts for a GitHub token. Starring is idempotent, so running the command again on an already-starred repository succeeds without any change. If the GitHub CLI is missing, logged out, or fails, the command opens the repository page in the default browser instead. The repository URL is always printed so it can be opened by hand when no browser is available.
+
+## Output
+On success, the human result names the starred repository, and machine formats emit one `setup.star` record on stdout. That record carries the repository, its URL, the method used (`gh` or `browser`), and whether the star was confirmed. A star made through the browser cannot be confirmed by the CLI, so that record reports it as unconfirmed. When the GitHub CLI path fails, the reason is written to stderr as a diagnostic before the browser fallback runs. Neither path changes local CLI configuration or Vidbyte credentials.
+
+## Examples
+Run `vidbyte-cli star` to star through the GitHub CLI when it is logged in. Run `vidbyte-cli star --browser` to skip the GitHub CLI and click Star on the repository page yourself. Run `gh auth login` first if you want the terminal path and the GitHub CLI is not yet logged in. Removing a star is done on the repository page, since this command only ever adds one.

vidbyte_cli/commands/setup/star.py

@@ -0,0 +1,132 @@
+"""`vidbyte-cli star` — stars the public Vidbyte CLI repository on GitHub.
+
+It runs only because a person typed it: starring on someone's behalf breaks GitHub's rules on
+inauthentic interactions, so no other command, hint, or error path may call it. The GitHub CLI
+owns authentication when it is present, so this package never holds a GitHub token; without
+it, the repository page opens and the person clicks Star themselves.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import click
+from pydantic import JsonValue
+
+from ...lib.output import OutputDocument
+from .prompts.library import SetupHelpLibrary
+
+if TYPE_CHECKING:
+    from ...lib.runtime.context import ApplicationContext
+
+# The public front-door repository, not the private source repository. It must name the same
+# repository as `Repository` under [project.urls]; scripts/test-star-command.py enforces that.
+REPOSITORY = "cerredz/vidbyte-cli"
+REPOSITORY_URL = f"https://github.com/{REPOSITORY}"
+_GH_TIMEOUT_SECONDS = 30
+
+_STAR_HELP = SetupHelpLibrary().load("star")
+_BROWSER_HELP = SetupHelpLibrary().load("browser")
+
+
+@dataclass(frozen=True, slots=True)
+class GhAttempt:
+    """Whether the GitHub CLI starred the repository, and why not when it did not."""
+
+    starred: bool
+    detail: str
+
+
+class GitHubCliStarrer:
+    """Stars a repository through the GitHub CLI's own login."""
+
+    def __init__(
+        self,
+        which: Callable[[str], str | None] = shutil.which,
+        run: Callable[..., subprocess.CompletedProcess[str]] = subprocess.run,
+    ) -> None:
+        self._which = which
+        self._run = run
+
+    def star(self, repository: str) -> GhAttempt:
+        executable = self._which("gh")
+        if executable is None:
+            return GhAttempt(starred=False, detail="the GitHub CLI (gh) is not installed")
+        # stdin is closed so a logged-out gh fails fast instead of waiting on a prompt.
+        command = [executable, "api", "--method", "PUT", f"/user/starred/{repository}", "--silent"]
+        try:
+            completed = self._run(
+                command,
+                stdin=subprocess.DEVNULL,
+                capture_output=True,
+                text=True,
+                check=False,
+                timeout=_GH_TIMEOUT_SECONDS,
+            )
+        except (OSError, subprocess.TimeoutExpired) as error:
+            return GhAttempt(starred=False, detail=f"the GitHub CLI could not run: {error}")
+        if completed.returncode == 0:
+            return GhAttempt(starred=True, detail="starred through the GitHub CLI")
+        reason = (completed.stderr or "").strip().splitlines()
+        detail = reason[-1] if reason else f"gh exited with status {completed.returncode}"
+        return GhAttempt(starred=False, detail=detail)
+
+
+class StarCommand:
+    """Registers the one command that stars the public repository, and only on request."""
+
+    def __init__(
+        self,
+        starrer: GitHubCliStarrer | None = None,
+        launch: Callable[[str], int] = click.launch,
+    ) -> None:
+        self._starrer = starrer or GitHubCliStarrer()
+        self._launch = launch
+
+    def register(self, parent: click.Group) -> None:
+        @parent.command(name="star", help=_STAR_HELP)
+        @click.option("--browser", is_flag=True, help=_BROWSER_HELP)
+        @click.pass_obj
+        def _run(context: ApplicationContext, browser: bool) -> None:
+            self.execute(context, browser)
+
+    def execute(self, context: ApplicationContext, browser: bool) -> None:
+        output = context.output()
+        if not browser:
+            attempt = self._starrer.star(REPOSITORY)
+            if attempt.starred:
+                output.result(
+                    self._document("gh", starred=True),
+                    f"Starred {REPOSITORY} on GitHub. Thank you!",
+                )
+                return
+            output.diagnostic(f"Could not star through the GitHub CLI: {attempt.detail}.")
+        opened = self._open_browser()
+        action = "Opened" if opened else "Open"
+        output.result(
+            self._document("browser", starred=False, browser_opened=opened),
+            f"{action} {REPOSITORY_URL} and click Star at the top right. Thank you!",
+        )
+
+    def _open_browser(self) -> bool:
+        # A headless machine has no browser; the printed URL is the fallback, not an error.
+        try:
+            return self._launch(REPOSITORY_URL) == 0
+        except OSError:
+            return False
+
+    @staticmethod
+    def _document(method: str, starred: bool, browser_opened: bool | None = None) -> OutputDocument:
+        data: dict[str, JsonValue] = {
+            "repository": REPOSITORY,
+            "url": REPOSITORY_URL,
+            "method": method,
+            "starred": starred,
+        }
+        if browser_opened is not None:
+            data["browser_opened"] = browser_opened
+        return OutputDocument(kind="setup.star", data=data)

vidbyte_cli/lib/api/client.py

@@ -0,0 +1,236 @@
+"""Typed HTTP client for the Vidbyte public API.
+
+Owns the base URL, API-key header injection, bounded response decoding, and status-driven
+failure classification. Commands never call httpx directly — all HTTP goes through a typed
+endpoint group built on this client.
+
+Settings and the credential arrive already resolved, so this client never reads the
+environment: doing so would let a stale variable outrank an explicit option and would skip
+the origin validation that `ResolvedConfig.api_url` has already passed.
+
+One request is serialized once and re-issued byte-identically under the same idempotency
+key, because every retry of a priced mutation must be the same mutation.
+Classification is by HTTP status only. The backend serves several different error-body
+shapes, so no single `code` field is a platform contract, and a generic client that knew one
+route's spelling would be wrong for the next one.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, TypeVar
+
+from pydantic import BaseModel
+
+from ..auth.credentials import Credentials
+from ..config import ResolvedConfig
+from ..errors.failures import ApiRouteMisconfigured
+from ..runtime.version import current_version
+from .response import ResponseDecoder, ResponseShape
+
+if TYPE_CHECKING:
+    import httpx
+
+    from .retry import RequestOutcome
+    from .runtime_payment import RuntimePayment
+
+# The backend reads this header first and accepts `Authorization: Bearer` only as a fallback,
+# so the key travels here and nowhere else. Sending both would be worse than sending one: the
+# gatekeeper stops at a malformed `x-api-key` instead of falling through to the bearer value.
+API_KEY_HEADER_NAME = "x-api-key"
+_MAX_CONNECTIONS = 20
+_MAX_KEEPALIVE_CONNECTIONS = 10
+
+TModel = TypeVar("TModel", bound=BaseModel)
+
+
+class ApiClient:
+    def __init__(self, config: ResolvedConfig, credentials: Credentials) -> None:
+        # Takes the invocation's resolved host, timeout, and secret; resolves nothing itself.
+        self.base_url = config.api_url.rstrip("/")
+        self.timeout_seconds = config.request_timeout_seconds
+        # The key is a secret: it is held here only to set the auth header, never logged.
+        self._credentials = credentials
+        # Built on first send, so constructing a client opens no socket and `--help` is free.
+        self._transport: httpx.Client | None = None
+        from .problem import ApiProblemMapper
+        from .retry import RetryPolicy
+
+        self._retry = RetryPolicy()
+        self._decoder = ResponseDecoder()
+        self._problems = ApiProblemMapper()
+
+    def auth_headers(self) -> dict[str, str]:
+        # The single point where the stored secret is unwrapped for transmission.
+        return {API_KEY_HEADER_NAME: self._credentials.secret_value()}
+
+    def get(
+        self,
+        path: str,
+        model: type[TModel],
+        *,
+        shape: ResponseShape = ResponseShape.ENVELOPE,
+    ) -> TModel:
+        # Performs an authenticated GET, unwraps the declared shape, validates into `model`.
+        return self.request("GET", path, response_model=model, response_shape=shape)
+
+    def post_direct(self, path: str, model: type[TModel]) -> TModel:
+        # POSTs with no body and validates the response object itself, not an envelope's `data`.
+        response = self._send("POST", path, None, None, route_not_found=True)
+        return self._decoder.one(response, model, ResponseShape.DIRECT)
+
+    def post(
+        self,
+        path: str,
+        body: BaseModel,
+        model: type[TModel],
+        *,
+        shape: ResponseShape = ResponseShape.ENVELOPE,
+        idempotency_key: str | None = None,
+    ) -> TModel:
+        # Performs an authenticated POST, unwraps the declared shape, validates into `model`.
+        return self.request(
+            "POST",
+            path,
+            response_model=model,
+            response_shape=shape,
+            body=body,
+            idempotency_key=idempotency_key,
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        response_model: type[TModel],
+        response_shape: ResponseShape,
+        body: BaseModel | None = None,
+        idempotency_key: str | None = None,
+    ) -> TModel:
+        # The one path every typed request takes: send with retries, then decode.
+        response = self._send(method, path, body, idempotency_key)
+        return self._decoder.one(response, response_model, response_shape)
+
+    def post_runtime_payment(
+        self, path: str, body: BaseModel, key: str, payer: RuntimePayment
+    ) -> httpx.Response:
+        # Probe or recover first, then authorize at most one exact x402 payment.
+        import httpx
+
+        from ..errors.failures import RuntimePaymentFailed
+
+        url = self._url(path)
+        content = self._content(body)
+        headers = self._headers(key, True)
+        outcome = self._retry_request("POST", url, content, headers)
+        if isinstance(outcome, httpx.Response) and outcome.status_code == 402:
+            headers.update(payer.headers(outcome))
+            outcome = self._retry_request("POST", url, content, headers)
+            if isinstance(outcome, httpx.Response) and outcome.status_code == 402:
+                raise RuntimePaymentFailed("payment_rejected")
+        return self._settle(outcome)
+
+    def close(self) -> None:
+        # Releases the connection pool; safe to call when no request was ever made.
+        if self._transport is not None:
+            self._transport.close()
+            self._transport = None
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        body: BaseModel | None,
+        idempotency_key: str | None,
+        *,
+        route_not_found: bool = False,
+    ) -> httpx.Response:
+        # Re-issues one identical request while the retry policy allows, then classifies.
+        url = self._url(path)
+        content = self._content(body)
+        headers = self._headers(idempotency_key, body is not None)
+        outcome = self._retry_request(method, url, content, headers)
+        return self._settle(outcome, route_not_found=route_not_found)
+
+    def _retry_request(
+        self, method: str, url: str, data: bytes | None, headers: dict[str, str]
+    ) -> RequestOutcome:
+        # Reuse identical signed bytes and request identity throughout bounded retries.
+        from .retry import RequestMetadata
+
+        metadata = RequestMetadata(method.upper(), "Idempotency-Key" in headers)
+        attempt = 1
+        while True:
+            outcome = self._attempt(method, url, data, headers)
+            decision = self._retry.decide(metadata, attempt, outcome)
+            if not decision.retry:
+                return outcome
+            time.sleep(decision.delay_seconds)
+            attempt += 1
+
+    def _attempt(
+        self,
+        method: str,
+        url: str,
+        content: bytes | None,
+        headers: dict[str, str],
+    ) -> RequestOutcome:
+        # One attempt is either a reply or a transport failure, never both and never neither.
+        import httpx
+
+        try:
+            return self._client().request(method, url, content=content, headers=headers)
+        except httpx.HTTPError as error:
+            return error
+
+    def _settle(self, outcome: RequestOutcome, *, route_not_found: bool = False) -> httpx.Response:
+        # The retry policy has given up, so this outcome is the caller's answer.
+        import httpx
+
+        if isinstance(outcome, httpx.HTTPError):
+            raise self._problems.from_transport(outcome) from outcome
+        if not 200 <= outcome.status_code < 300:
+            raise self._problems.from_response(outcome, route_not_found=route_not_found)
+        return outcome
+
+    def _client(self) -> httpx.Client:
+        # Built once per invocation so a watch loop reuses one pool across many polls.
+        import httpx
+
+        if self._transport is None:
+            self._transport = httpx.Client(
+                timeout=httpx.Timeout(self.timeout_seconds),
+                follow_redirects=False,
+                limits=httpx.Limits(
+                    max_connections=_MAX_CONNECTIONS,
+                    max_keepalive_connections=_MAX_KEEPALIVE_CONNECTIONS,
+                ),
+            )
+        return self._transport
+
+    def _content(self, body: BaseModel | None) -> bytes | None:
+        # Serialized once so every attempt is byte-identical, and `exclude_none` is what
+        # keeps unset options out of a request DTO the backend validates with extra="forbid".
+        if body is None:
+            return None
+        return body.model_dump_json(exclude_none=True, by_alias=True).encode("utf-8")
+
+    def _url(self, path: str) -> str:
+        # A route carrying its own scheme or host would send the key to an unconfigured origin.
+        if not path.startswith("/") or path.startswith("//") or "://" in path:
+            raise ApiRouteMisconfigured()
+        return f"{self.base_url}{path}"
+
+    def _headers(self, idempotency_key: str | None, has_body: bool) -> dict[str, str]:
+        # Identity, content negotiation, and the credential; nothing derived from user input.
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": f"vidbyte-cli/{current_version()}",
+            **self.auth_headers(),
+        }
+        if has_body:
+            headers["Content-Type"] = "application/json"
+        if idempotency_key is not None:
+            headers["Idempotency-Key"] = idempotency_key
+        return headers

vidbyte_cli/lib/api/endpoints/auth.py

@@ -0,0 +1,24 @@
+"""The one authentication route the CLI calls, and the identity it returns.
+
+`validate` is the only permission-free liveness check the backend serves. It is chosen over a
+cheap authenticated resource read because the API grants read and write scopes separately: a
+key scoped only to write is perfectly valid, and a read-based check would refuse to log it in.
+Capability belongs at the point of use, where a rejection can name the missing scope.
+"""
+
+from __future__ import annotations
+
+from ....types.api import KeyIdentity
+from ..client import ApiClient
+
+AUTH_VALIDATE_PATH = "/api/skills/auth/validate"
+
+
+class AuthEndpoints:
+    def __init__(self, client: ApiClient) -> None:
+        # Binds the endpoint group to a configured ApiClient.
+        self._client = client
+
+    def validate(self) -> KeyIdentity:
+        # Proves the configured key is live and returns its non-secret identity.
+        return self._client.post_direct(AUTH_VALIDATE_PATH, KeyIdentity)

vidbyte_cli/lib/api/endpoints/billing.py

@@ -0,0 +1,36 @@
+"""Authenticated billing operations exposed by the Vidbyte API."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from uuid import uuid4
+
+from ....types.api import BillingTopUpResult
+from ....types.runtime import RuntimeAdmissionRequest, RuntimeHost
+from ..client import ApiClient
+from ..response import ResponseDecoder, ResponseShape
+
+if TYPE_CHECKING:
+    from ..runtime_payment import RuntimePayment
+
+TOP_UP_PATH = "/agent/topup"
+TOP_UP_CENTS = 500
+
+
+class BillingEndpoints:
+    """Billing operations bound to one authenticated API client."""
+
+    def __init__(self, client: ApiClient) -> None:
+        # Retains the invocation-owned client without opening a connection.
+        self._client = client
+
+    def top_up(self, key: str | None, payer: RuntimePayment) -> BillingTopUpResult:
+        # Pays one exact top-up challenge and validates the credited balance response.
+        idempotency_key = key or str(uuid4())
+        response = self._client.post_runtime_payment(
+            TOP_UP_PATH,
+            RuntimeAdmissionRequest(host=RuntimeHost.CODEX),
+            idempotency_key,
+            payer,
+        )
+        return ResponseDecoder().one(response, BillingTopUpResult, ResponseShape.DIRECT)

vidbyte_cli/lib/api/endpoints/research.py

@@ -0,0 +1,103 @@
+"""Typed wrappers for the /api/v1/research/* public API routes.
+
+These six are the entire surface an API key may call. There is no sources, artifacts,
+capabilities, exports, or run-listing route, so there is no method here for one.
+
+Every route returns its DTO directly rather than inside the `{success, data}` envelope the
+older public resources use, which is why each call names `ResponseShape.DIRECT` explicitly.
+"""
+
+from __future__ import annotations
+
+from urllib.parse import quote, urlencode
+
+from ....types.research import (
+    ResearchPortfolioPage,
+    ResearchRunAccepted,
+    ResearchRunCreateRequest,
+    ResearchRunStatus,
+    ResearchThreadDetail,
+)
+from ..client import ApiClient
+from ..response import ResponseShape
+
+_RESEARCH_ROOT = "/api/v1/research"
+
+
+class ResearchEndpoints:
+    def __init__(self, client: ApiClient) -> None:
+        # Binds the endpoint group to a configured ApiClient.
+        self._client = client
+
+    def create_run(
+        self,
+        request: ResearchRunCreateRequest,
+        idempotency_key: str,
+    ) -> ResearchRunAccepted:
+        # POST /api/v1/research/run — opens a new thread and admits its first run.
+        return self._client.post(
+            f"{_RESEARCH_ROOT}/run",
+            request,
+            ResearchRunAccepted,
+            shape=ResponseShape.DIRECT,
+            idempotency_key=idempotency_key,
+        )
+
+    def append_run(
+        self,
+        thread_id: str,
+        request: ResearchRunCreateRequest,
+        idempotency_key: str,
+    ) -> ResearchRunAccepted:
+        # POST /api/v1/research/threads/{id}/run — admits another prompt into one thread.
+        return self._client.post(
+            f"{_RESEARCH_ROOT}/threads/{self._segment(thread_id)}/run",
+            request,
+            ResearchRunAccepted,
+            shape=ResponseShape.DIRECT,
+            idempotency_key=idempotency_key,
+        )
+
+    def continue_run(self, run_id: str, idempotency_key: str) -> ResearchRunAccepted:
+        # POST /api/v1/research/runs/{id}/continue — reopens one terminal-resumable run.
+        # The route takes no body: a continuation replays the original prompt, never a new one.
+        return self._client.request(
+            "POST",
+            f"{_RESEARCH_ROOT}/runs/{self._segment(run_id)}/continue",
+            response_model=ResearchRunAccepted,
+            response_shape=ResponseShape.DIRECT,
+            idempotency_key=idempotency_key,
+        )
+
+    def get_run(self, run_id: str) -> ResearchRunStatus:
+        # GET /api/v1/research/runs/{id} — one run's coarse durable status.
+        return self._client.get(
+            f"{_RESEARCH_ROOT}/runs/{self._segment(run_id)}",
+            ResearchRunStatus,
+            shape=ResponseShape.DIRECT,
+        )
+
+    def get_portfolio(self, cursor: str | None, limit: int | None) -> ResearchPortfolioPage:
+        # GET /api/v1/research/portfolio — one bounded page of the caller's threads.
+        return self._client.get(
+            self._paged(f"{_RESEARCH_ROOT}/portfolio", cursor, limit),
+            ResearchPortfolioPage,
+            shape=ResponseShape.DIRECT,
+        )
+
+    def get_thread(self, thread_id: str) -> ResearchThreadDetail:
+        # GET /api/v1/research/threads/{id} — one owned thread and its rollup counters.
+        return self._client.get(
+            f"{_RESEARCH_ROOT}/threads/{self._segment(thread_id)}",
+            ResearchThreadDetail,
+            shape=ResponseShape.DIRECT,
+        )
+
+    def _segment(self, value: str) -> str:
+        # Encoding an opaque identifier means it can never alter the route's structure.
+        return quote(value, safe="")
+
+    def _paged(self, path: str, cursor: str | None, limit: int | None) -> str:
+        # Unset parameters are omitted so the server keeps ownership of both defaults.
+        query = {name: value for name, value in (("cursor", cursor), ("limit", limit)) if value}
+        return f"{path}?{urlencode(query)}" if query else path