runtime-sdk 0.4.49__py3-none-win_amd64.whl

runtime_sdk/github.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+import contextlib
+import re
+import time
+import webbrowser
+
+from runtime_sdk import output as cli_output, terminal
+from runtime_sdk.auth import authenticated_client
+from runtime_sdk.client import RuntimeAPIError
+from runtime_sdk.config import RuntimeConfig
+
+
+def _coerce_github_repo(repo: str | None) -> str | None:
+    text = str(repo or "").strip()
+    if not text:
+        return None
+    if not re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", text):
+        raise RuntimeAPIError("repo must be in owner/name format")
+    owner, name = text.split("/", 1)
+    return f"{owner}/{name}"
+
+
+def _coerce_git_branch(branch: str | None) -> str | None:
+    text = str(branch or "").strip()
+    if not text:
+        return None
+    if text == "@":
+        raise RuntimeAPIError("branch name is invalid")
+    if (
+        text.startswith("-")
+        or text.endswith("/")
+        or text.endswith(".")
+        or text.endswith(".lock")
+    ):
+        raise RuntimeAPIError("branch name is invalid")
+    if ".." in text or "//" in text or "@{" in text:
+        raise RuntimeAPIError("branch name is invalid")
+    if any(ch in text for ch in (" ", "~", "^", ":", "?", "*", "[", "\\")):
+        raise RuntimeAPIError("branch name is invalid")
+    if any(ord(ch) < 32 or ord(ch) == 127 for ch in text):
+        raise RuntimeAPIError("branch name is invalid")
+    return text
+
+
+def handle_github_list(config: RuntimeConfig) -> int:
+    if (err := cli_output.require_auth(config)) is not None:
+        return err
+    client = authenticated_client(config)
+    return cli_output.report_success(client.list_github_installations())
+
+
+def handle_github_disconnect(config: RuntimeConfig, ref: str | None) -> int:
+    if (err := cli_output.require_auth(config)) is not None:
+        return err
+    resolved_ref = str(ref or "").strip()
+    if not resolved_ref:
+        if not cli_output.interactive():
+            return cli_output.report_error(
+                "github owner or installation id is required"
+            )
+        resolved_ref = cli_output.prompt_text("GitHub owner or installation id")
+        if not resolved_ref:
+            return cli_output.report_error(
+                "github owner or installation id is required"
+            )
+
+    client = authenticated_client(config)
+    installation_id: int | None = None
+    owner = resolved_ref
+
+    try:
+        installation_id = int(resolved_ref)
+    except ValueError:
+        payload = client.list_github_installations()
+        installations = payload.get("installations") or []
+        target_owner = resolved_ref.casefold()
+        match = next(
+            (
+                entry
+                for entry in installations
+                if isinstance(entry, dict)
+                and str(entry.get("github_account_login") or "").strip().casefold()
+                == target_owner
+            ),
+            None,
+        )
+        if match is None:
+            return cli_output.report_error(
+                f"github installation not found: {resolved_ref}"
+            )
+        try:
+            installation_id = int(match.get("id"))
+        except (TypeError, ValueError):
+            return cli_output.report_error(
+                f"github installation is missing an id: {resolved_ref}"
+            )
+        owner = str(match.get("github_account_login") or resolved_ref)
+
+    if installation_id is None or installation_id <= 0:
+        return cli_output.report_error("installation id must be a positive number")
+
+    client.disconnect_github_installation(installation_id)
+    return cli_output.report_success(
+        {"id": installation_id, "owner": owner, "deleted": True}
+    )
+
+
+def handle_integrate_github(
+    config: RuntimeConfig,
+    provider: str,
+    *,
+    no_open: bool = False,
+    timeout_seconds: int = 180,
+) -> int:
+    if (err := cli_output.require_auth(config)) is not None:
+        return err
+    if provider != "github":
+        return cli_output.report_error(f"unsupported integration provider: {provider}")
+
+    client = authenticated_client(config)
+    payload = client.start_github_connect()
+    install_url = str(payload.get("install_url") or "").strip()
+    session_id = int(payload.get("session_id") or 0)
+    if not install_url or session_id <= 0:
+        return cli_output.report_error("server did not return a GitHub install session")
+
+    opened = False
+    if not no_open:
+        with contextlib.suppress(Exception):
+            opened = bool(webbrowser.open(install_url))
+
+    if cli_output.interactive():
+        action = (
+            "opened in your browser" if opened else "copy this URL into your browser"
+        )
+        print(f"{action}: {install_url}")
+        print(
+            "Choose the GitHub account or organization and repository access. Waiting for completion..."
+        )
+
+    deadline = time.time() + max(1, int(timeout_seconds))
+    last_status = "pending"
+    while time.time() < deadline:
+        session = client.get_github_connect_session(session_id)
+        status = str(session.get("status") or "pending")
+        last_status = status
+        if status == "completed":
+            installation = session.get("installation") or {}
+            return cli_output.report_success(
+                {
+                    "installation": installation,
+                    "install_url": install_url,
+                    "session_id": session_id,
+                }
+            )
+        if status in {"failed", "expired"}:
+            return cli_output.report_error(
+                str(session.get("error") or f"github connect {status}")
+            )
+        time.sleep(2)
+
+    return cli_output.report_error(
+        f"timed out waiting for GitHub install to finish (last status: {last_status})"
+    )
+
+
+def handle_switch(
+    config: RuntimeConfig,
+    repo: str | None,
+    branch: str | None,
+    *,
+    create_branch: bool = False,
+    base_branch: str | None = None,
+) -> int:
+    if (err := cli_output.require_auth(config)) is not None:
+        return err
+    if base_branch is not None and not create_branch:
+        return cli_output.report_error("--from can only be used together with -c")
+
+    try:
+        resolved_repo = _coerce_github_repo(repo)
+        resolved_branch = _coerce_git_branch(branch)
+    except RuntimeAPIError as exc:
+        return cli_output.report_error(str(exc), status_code=exc.status_code)
+
+    if resolved_repo is None:
+        if not cli_output.interactive():
+            return cli_output.report_error("--repo is required")
+        resolved_repo = cli_output.prompt_text("GitHub repo (owner/name)")
+        try:
+            resolved_repo = _coerce_github_repo(resolved_repo)
+        except RuntimeAPIError as exc:
+            return cli_output.report_error(str(exc), status_code=exc.status_code)
+        if resolved_repo is None:
+            return cli_output.report_error("repo is required")
+
+    if resolved_branch is None:
+        if not cli_output.interactive():
+            return cli_output.report_error("branch is required")
+        prompt = "New branch name" if create_branch else "Branch name"
+        resolved_branch = cli_output.prompt_text(prompt)
+        try:
+            resolved_branch = _coerce_git_branch(resolved_branch)
+        except RuntimeAPIError as exc:
+            return cli_output.report_error(str(exc), status_code=exc.status_code)
+        if resolved_branch is None:
+            return cli_output.report_error("branch is required")
+
+    client = authenticated_client(config)
+    try:
+        payload = client.switch_workspace(
+            repo=resolved_repo,
+            branch=resolved_branch,
+            create=create_branch,
+            base_branch=base_branch,
+        )
+    except RuntimeAPIError as exc:
+        return cli_output.report_error(str(exc), status_code=exc.status_code)
+
+    computer = payload.get("computer") or {}
+    computer_id = str(computer.get("id") or "").strip()
+    if not computer_id:
+        return cli_output.report_error("server did not return a computer id")
+
+    code = cli_output.report_success(payload)
+    if code != 0 or not cli_output.interactive():
+        return code
+    return terminal.enter_computer(config, computer_id)

runtime_sdk/goals.py

@@ -0,0 +1,368 @@
+from __future__ import annotations
+
+import json
+import re
+import time
+from datetime import datetime
+from typing import Any
+
+from runtime_sdk import computers, output as cli_output
+from runtime_sdk.auth import authenticated_client
+from runtime_sdk.client import RuntimeAPIError, RuntimeClient
+from runtime_sdk.config import RuntimeConfig
+
+
+GOAL_WATCH_DIR = "/home/runtime/.runtime/email-goals"
+
+
+def _goal_emit(tag: str, message: Any) -> None:
+    text = str(message or "").rstrip()
+    if not text:
+        return
+    lines = text.splitlines() or [text]
+    for index, line in enumerate(lines):
+        prefix = f"[{tag}] " if index == 0 else " " * (len(tag) + 3)
+        print(prefix + line, flush=True)
+
+
+def _goal_parse_time(value: Any) -> float:
+    if not value:
+        return 0.0
+    text = str(value)
+    match = re.match(r"^(.*T\d\d:\d\d:\d\d)(?:\.(\d+))?(Z|[+-]\d\d:\d\d)?$", text)
+    if match:
+        fraction = match.group(2) or ""
+        suffix = match.group(3) or ""
+        text = match.group(1)
+        if fraction:
+            text += "." + fraction[:6].ljust(6, "0")
+        text += suffix
+    try:
+        return datetime.fromisoformat(text.replace("Z", "+00:00")).timestamp()
+    except ValueError:
+        return 0.0
+
+
+def _goal_read_text(client: RuntimeClient, computer_id: str, path: str) -> str | None:
+    try:
+        return client.read_file(computer_id, path).decode("utf-8", errors="replace")
+    except RuntimeAPIError as exc:
+        if exc.status_code == 404:
+            return None
+        raise
+
+
+def _goal_read_json(
+    client: RuntimeClient, computer_id: str, path: str
+) -> dict[str, Any] | None:
+    text = _goal_read_text(client, computer_id, path)
+    if not text:
+        return None
+    try:
+        payload = json.loads(text)
+    except ValueError:
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def _goal_list_logs(client: RuntimeClient, computer_id: str) -> list[dict[str, Any]]:
+    try:
+        payload = client.list_files(computer_id, GOAL_WATCH_DIR)
+    except RuntimeAPIError as exc:
+        if exc.status_code == 404:
+            return []
+        raise
+    entries = payload.get("entries") or []
+    logs = [
+        entry
+        for entry in entries
+        if isinstance(entry, dict) and str(entry.get("name") or "").endswith(".log")
+    ]
+    return sorted(logs, key=lambda entry: _goal_parse_time(entry.get("mtime")))
+
+
+def _goal_run_json(
+    client: RuntimeClient, computer_id: str, command: str
+) -> dict[str, Any] | None:
+    try:
+        result = client.run_command(
+            computer_id,
+            command,
+            uid=1000,
+            gid=1000,
+            cwd="/home/runtime",
+            shell="/bin/bash",
+        )
+    except RuntimeAPIError:
+        return None
+    if int(result.get("exit_code") or 0) != 0:
+        return None
+    try:
+        payload = json.loads(result.get("stdout") or "{}")
+    except ValueError:
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def _goal_run_text(client: RuntimeClient, computer_id: str, command: str) -> str:
+    try:
+        result = client.run_command(
+            computer_id,
+            command,
+            uid=1000,
+            gid=1000,
+            cwd="/home/runtime",
+            shell="/bin/bash",
+        )
+    except RuntimeAPIError:
+        return ""
+    if int(result.get("exit_code") or 0) != 0:
+        return ""
+    return str(result.get("stdout") or "").strip()
+
+
+def _goal_current_email_ids(client: RuntimeClient, computer_id: str) -> set[str]:
+    payload = _goal_run_json(client, computer_id, "runtime-env email inbox --json")
+    emails = payload.get("emails") if isinstance(payload, dict) else []
+    return {
+        str(item.get("id") or "")
+        for item in emails or []
+        if isinstance(item, dict) and item.get("id")
+    }
+
+
+def _goal_render_log_line(line: str, state: dict[str, Any]) -> None:
+    text = str(line or "").strip()
+    if not text:
+        return
+    mappings = (
+        ("assistant final_answer: ", "agent-final"),
+        ("assistant commentary: ", "agent"),
+        ("assistant analysis: ", "agent"),
+        ("assistant message: ", "agent"),
+        ("assistant delta: ", "agent"),
+        ("started command: ", "cmd"),
+        ("command: ", "cmd"),
+        ("command output delta: ", "out"),
+        ("command output: ", "out"),
+        ("file change: ", "file"),
+        ("mcp tool: ", "mcp"),
+        ("token usage: ", "usage"),
+        ("codex turn started", "codex"),
+        ("codex turn completed: ", "codex"),
+    )
+    for prefix, tag in mappings:
+        if text.startswith(prefix):
+            state["native_codex_stream_seen"] = True
+            value = text[len(prefix) :] if text != prefix.strip() else text
+            if tag == "cmd" and value.startswith("command: "):
+                value = value[len("command: ") :]
+            _goal_emit(tag, value)
+            return
+    _goal_emit("goal", text)
+
+
+def _goal_wait_for_target(
+    client: RuntimeClient,
+    computer_id: str,
+    *,
+    mode: str,
+    email_id: str | None,
+    baseline: set[str],
+    deadline: float | None,
+) -> str:
+    if email_id:
+        _goal_emit("watch", f"waiting for {email_id}")
+        while True:
+            logs = _goal_list_logs(client, computer_id)
+            if any(entry.get("name") == f"{email_id}.log" for entry in logs):
+                return email_id
+            _goal_check_timeout(deadline)
+            time.sleep(0.75)
+
+    _goal_emit(
+        "watch",
+        "waiting for next email goal"
+        if mode == "next"
+        else "waiting for latest email goal",
+    )
+    while True:
+        logs = _goal_list_logs(client, computer_id)
+        if mode == "next":
+            logs = [
+                entry for entry in logs if str(entry.get("name") or "") not in baseline
+            ]
+        if logs:
+            return str(logs[-1].get("name") or "").removesuffix(".log")
+        _goal_check_timeout(deadline)
+        time.sleep(0.75)
+
+
+def _goal_check_timeout(deadline: float | None) -> None:
+    if deadline is not None and time.time() >= deadline:
+        _goal_emit("watch", "timeout reached")
+        raise TimeoutError
+
+
+def _goal_poll_mail(
+    client: RuntimeClient,
+    computer_id: str,
+    seen: set[str],
+    target_email_id: str,
+    started_at: float,
+) -> None:
+    payload = _goal_run_json(client, computer_id, "runtime-env email inbox --json")
+    emails = payload.get("emails") if isinstance(payload, dict) else []
+    for item in sorted(
+        (email for email in emails or [] if isinstance(email, dict)),
+        key=lambda email: _goal_parse_time(email.get("created_at")),
+    ):
+        item_id = str(item.get("id") or "")
+        if not item_id or item_id in seen:
+            continue
+        created = _goal_parse_time(item.get("created_at"))
+        if item_id != target_email_id and created and created < started_at - 5:
+            seen.add(item_id)
+            continue
+        seen.add(item_id)
+        direction = item.get("direction") or "email"
+        status = item.get("status") or ""
+        subject = item.get("subject") or ""
+        _goal_emit("mail", f"{direction} {status} {item_id}: {subject}".strip())
+
+
+def _goal_poll_service(
+    client: RuntimeClient, computer_id: str, last_status: str
+) -> str:
+    status = _goal_run_text(client, computer_id, "runtime-env service status")
+    if status and status != last_status:
+        _goal_emit("service", status)
+        return status
+    return last_status
+
+
+def _goal_describe(client: RuntimeClient, computer_id: str, email_id: str) -> None:
+    metadata = _goal_read_json(client, computer_id, f"{GOAL_WATCH_DIR}/{email_id}.json")
+    if not metadata:
+        return
+    sender = metadata.get("from") or ""
+    to = ", ".join(metadata.get("to") or [])
+    subject = metadata.get("subject") or ""
+    _goal_emit("mail", f"received {email_id} from {sender} to {to}: {subject}")
+
+
+def _goal_watch_polling(
+    client: RuntimeClient,
+    computer_id: str,
+    *,
+    mode: str,
+    email_id: str | None,
+    timeout: int,
+) -> int:
+    started_at = time.time()
+    deadline = started_at + timeout if timeout > 0 else None
+    baseline_logs = (
+        {str(entry.get("name") or "") for entry in _goal_list_logs(client, computer_id)}
+        if mode == "next"
+        else set()
+    )
+    seen_emails = (
+        _goal_current_email_ids(client, computer_id) if mode == "next" else set()
+    )
+    state: dict[str, Any] = {"native_codex_stream_seen": False}
+
+    try:
+        target_email_id = _goal_wait_for_target(
+            client,
+            computer_id,
+            mode=mode,
+            email_id=email_id,
+            baseline=baseline_logs,
+            deadline=deadline,
+        )
+    except TimeoutError:
+        return 124
+
+    target_log = f"{GOAL_WATCH_DIR}/{target_email_id}.log"
+    target_response = f"{GOAL_WATCH_DIR}/{target_email_id}.response.md"
+    target_started_at = time.time()
+    offset = 0
+    response_printed = False
+    done_seen_at: float | None = None
+    last_mail_poll = 0.0
+    last_service_poll = 0.0
+    last_service_status = ""
+
+    _goal_emit("goal", f"watching {target_email_id}")
+    _goal_describe(client, computer_id, target_email_id)
+
+    while True:
+        try:
+            _goal_check_timeout(deadline)
+        except TimeoutError:
+            return 124
+        now = time.time()
+
+        text = _goal_read_text(client, computer_id, target_log) or ""
+        if len(text) < offset:
+            offset = 0
+        if len(text) > offset:
+            chunk = text[offset:]
+            offset = len(text)
+            for line in chunk.splitlines():
+                _goal_render_log_line(line, state)
+
+        if now - last_mail_poll >= 2:
+            _goal_poll_mail(
+                client, computer_id, seen_emails, target_email_id, target_started_at
+            )
+            last_mail_poll = now
+
+        if now - last_service_poll >= 2:
+            last_service_status = _goal_poll_service(
+                client, computer_id, last_service_status
+            )
+            last_service_poll = now
+
+        if not response_printed:
+            response = (
+                _goal_read_text(client, computer_id, target_response) or ""
+            ).strip()
+            if response:
+                _goal_emit("done", response)
+                response_printed = True
+                done_seen_at = now
+
+        if done_seen_at is not None and now - done_seen_at >= 3:
+            return 0
+
+        time.sleep(0.75)
+
+
+def handle_goal_watch(
+    config: RuntimeConfig,
+    computer_id: str | None,
+    *,
+    latest: bool,
+    next_goal: bool,
+    email_id: str | None,
+    timeout: int,
+) -> int:
+    if (err := cli_output.require_auth(config)) is not None:
+        return err
+    if not computer_id:
+        return cli_output.report_error("computer id is required")
+    if latest and next_goal:
+        return cli_output.report_error("--latest and --next cannot be used together")
+    if email_id and next_goal:
+        return cli_output.report_error("--email-id and --next cannot be used together")
+    if timeout < 0:
+        return cli_output.report_error("--timeout must be non-negative")
+
+    mode = "email" if email_id else "next" if next_goal else "latest"
+
+    client = authenticated_client(config)
+    computer_id = computers.resolve_computer_ref(client, computer_id)
+    return _goal_watch_polling(
+        client, computer_id, mode=mode, email_id=email_id, timeout=timeout
+    )

runtime_sdk/output.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import getpass
+import json
+import os
+import sys
+from typing import Any
+
+from runtime_sdk.auth import has_credentials
+from runtime_sdk.config import RuntimeConfig
+
+
+def interactive() -> bool:
+    if os.environ.get("RUNTIME_NO_TTY"):
+        return False
+    try:
+        return sys.stdin.isatty() and sys.stdout.isatty()
+    except (AttributeError, ValueError):
+        return False
+
+
+def write_json(payload: dict[str, Any], *, error: bool = False) -> int:
+    stream = sys.stderr if error else sys.stdout
+    stream.write(json.dumps(payload) + "\n")
+    stream.flush()
+    return 1 if error else 0
+
+
+def report_error(message: str, *, status_code: int | None = None) -> int:
+    payload: dict[str, Any] = {"success": False, "error": message}
+    if status_code is not None:
+        payload["status_code"] = status_code
+    return write_json(payload, error=True)
+
+
+def report_success(payload: dict[str, Any]) -> int:
+    return write_json({"success": True, **payload})
+
+
+def require_auth(config: RuntimeConfig) -> int | None:
+    if has_credentials(config):
+        return None
+    return report_error("not logged in; run runtime login", status_code=401)
+
+
+def require_interactive_session(config: RuntimeConfig) -> int | None:
+    if has_credentials(config, interactive=True):
+        return None
+    return report_error(
+        "interactive WorkOS login required; run runtime login", status_code=401
+    )
+
+
+def prompt_text(message: str, *, default: str | None = None) -> str | None:
+    suffix = f" [{default}]" if default else ""
+    answer = input(f"{message}{suffix}: ")
+    if not answer and default is not None:
+        answer = default
+    return answer.strip() or None
+
+
+def prompt_password(message: str) -> str | None:
+    answer = getpass.getpass(f"{message}: ")
+    return answer.strip() or None
+
+
+def prompt_typed_confirm(message: str, expected: str) -> bool:
+    answer = prompt_text(f"{message} (type {expected!r} to confirm)") or ""
+    return answer.strip().lower() == expected.strip().lower()