| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420 |
- """``hermes photon ...`` CLI subcommands (registered via ``ctx.register_cli_command()``):
- setup (device login + project + user + sidecar), status, install-sidecar (npm install in
- the sidecar dir), telemetry [on|off]. Device login is the first step of ``setup`` (no
- standalone ``login`` verb); inbound is the gRPC stream, so there are no webhook subcommands.
- """
- from __future__ import annotations
- import argparse
- import getpass
- import os
- import subprocess
- import sys
- from typing import Optional
- from hermes_cli.colors import Colors, color
- from . import auth as photon_auth
- from .adapter import sidecar_deps_installed
- from hermes_constants import find_node_executable, with_hermes_node_path
- from .sidecar_paths import _NPM_ERROR_LOG_MAX_CHARS, _npm_error_log, _sidecar_dir
- import contextlib
- def register_cli(parser: argparse.ArgumentParser) -> None:
- """Wire up `hermes photon ...` subcommands."""
- subs = parser.add_subparsers(dest="photon_command", required=False)
- p_setup = subs.add_parser("setup", help="First-time setup (device login + project + user + sidecar)")
- p_setup.add_argument("--project-name", default=None, help="Project name (default: 'Hermes Agent')")
- p_setup.add_argument("--phone", default=None, help="Your E.164 phone number (e.g. +15551234567)")
- p_setup.add_argument("--first-name", default=None)
- p_setup.add_argument("--last-name", default=None)
- p_setup.add_argument("--email", default=None)
- p_setup.add_argument("--no-browser", action="store_true",
- help="Don't try to open a browser for device login; print the URL only")
- p_setup.add_argument("--skip-sidecar-install", action="store_true",
- help="Skip `npm install` inside the sidecar directory")
- subs.add_parser("status", help="Show login + project + sidecar dep state")
- subs.add_parser("install-sidecar", help="Run npm install inside the sidecar directory")
- p_telemetry = subs.add_parser("telemetry", help="Show or toggle Spectrum SDK telemetry (on/off)")
- p_telemetry.add_argument(
- "state", nargs="?", choices=("on", "off"),
- help="Turn telemetry on or off (omit to show the current state)")
- parser.set_defaults(func=dispatch)
- def dispatch(args: argparse.Namespace) -> int:
- sub = getattr(args, "photon_command", None)
- handler = _cmd_status if sub is None else _COMMANDS.get(sub) # no subcommand — status by default
- if handler is None:
- print(f"unknown subcommand: {sub}", file=sys.stderr)
- return 2
- return handler(args)
- # -- Subcommand handlers -------------------------------------------------------------
- def _run_device_login(args: argparse.Namespace) -> int:
- """Run the RFC 8628 device-code login flow and persist the token (first step of ``setup``)."""
- def _print_code(code):
- print("\n┌─ Photon device login ────────────────────────────────────────\n"
- f"│ Open this URL: {code.verification_uri_complete or code.verification_uri}\n"
- f"│ Enter the code: {code.user_code}\n"
- "│ (waiting for approval — Ctrl-C to cancel)\n"
- "└──────────────────────────────────────────────────────────────\n")
- try:
- photon_auth.login_device_flow(open_browser=not args.no_browser, on_user_code=_print_code)
- except Exception as e:
- print(f"login failed: {e}", file=sys.stderr)
- return 1
- # Never print any portion of the token (shoulder-surfing / screen recordings).
- print(f"✓ logged in — token saved to {photon_auth._auth_json_path()}")
- return 0
- def _setup_token(args: argparse.Namespace) -> Optional[str]:
- """[1/5] Reuse a valid dashboard token or run device login; None on failure."""
- token = photon_auth.load_photon_token()
- if token:
- # The dashboard token has a short TTL (~3-4 days); a stale one makes every management
- # call 401, so validate upfront and fall back to a fresh login.
- print("[1/5] Checking existing Photon token...")
- if photon_auth.check_photon_token_valid(token):
- print(" ✓ token is valid")
- print("[1/5] Reusing existing Photon token")
- return token
- print(" ✗ token is stale (dashboard rejected it) — re-authenticating")
- photon_auth.clear_photon_token()
- print("[1/5] No valid Photon token found — running device login...")
- if _run_device_login(args) != 0:
- return None
- token = photon_auth.load_photon_token()
- if not token:
- print("login completed but token was not stored", file=sys.stderr)
- return token
- def _setup_project(token: str, name: str) -> Optional[str]:
- """[2/5] Find or create the project; returns its id or None on failure."""
- dashboard_id = photon_auth.load_dashboard_project_id()
- try:
- if dashboard_id:
- print("[2/5] Reusing configured Photon project")
- elif (existing := photon_auth.find_project_by_name(token, name)) and existing.get("id"):
- dashboard_id = existing["id"]
- print(f"[2/5] Found existing project '{name}'")
- else:
- print(f"[2/5] Creating Photon project '{name}'...")
- dashboard_id = photon_auth.create_project(token, name=name).get("id")
- print(" ✓ project created")
- except Exception as e:
- print(f"project setup failed: {e}", file=sys.stderr)
- return None
- if not dashboard_id:
- print("could not resolve a Photon project id", file=sys.stderr)
- return None
- return dashboard_id
- def _setup_credentials(token: str, dashboard_id: str, name: str) -> Optional[str]:
- """[3/5] Provision Spectrum credentials (runtime -> .env, ids -> auth.json); the dashboard
- id *is* the Spectrum id. A valid existing secret is reused: regenerating breaks a running
- sidecar's sends until restart. Returns the secret or None."""
- try:
- # 3. Spectrum is always enabled and provisioned at create-time, and the dashboard project id *is*
- # the Spectrum project id (ids unified), so there's nothing to enable — the id we already have is
- # the Spectrum id. Regenerating invalidates the credential that a running sidecar holds in its
- # process env, causing all outbound sends to fail with AuthenticationError until the gateway is
- # restarted (GH #50755).
- print("[3/5] Provisioning Spectrum credentials...")
- existing_id, existing_secret = photon_auth.load_project_credentials()
- secret: str = ""
- if existing_id and existing_secret:
- with contextlib.suppress(Exception): # failure => fall through to regeneration
- photon_auth.list_users(existing_id, existing_secret) # lightweight validation
- secret = existing_secret
- reused = bool(secret)
- if not secret:
- secret = photon_auth.regenerate_project_secret(token, dashboard_id)
- photon_auth.store_project_credentials(
- spectrum_project_id=dashboard_id, project_secret=secret, dashboard_project_id=dashboard_id, name=name)
- if reused:
- print(f" ✓ Spectrum ready (project id {dashboard_id}) — existing credentials valid")
- else:
- print(f" ✓ Spectrum ready (project id {dashboard_id}) — new secret saved")
- print(" ⚠ Project secret was regenerated. If the gateway is running, "
- "restart it so the sidecar picks up the new secret:\n"
- " hermes gateway restart")
- except Exception as e:
- print(f"spectrum provisioning failed: {e}", file=sys.stderr)
- return None
- return secret
- def _cmd_setup(args: argparse.Namespace) -> int:
- name = args.project_name or photon_auth.DEFAULT_PROJECT_NAME
- token = _setup_token(args)
- dashboard_id = token and _setup_project(token, name)
- secret = dashboard_id and _setup_credentials(token, dashboard_id, name)
- if not secret:
- return 1
- # 4. Register the operator's phone number as a Spectrum user (idempotent).
- phone = args.phone or _prompt(color("[4/5] Your iMessage phone number (E.164, e.g. +15551234567): ", Colors.CYAN))
- agent_number = registered_phone = registered_user_id = None
- routing_live = False # only an opted-in, registered number makes setup "complete"
- if not phone:
- print(" Skipped user registration (no phone given). Re-run with --phone later.")
- else:
- try: # name/email are optional and never prompted for (--first-name / --email)
- user, created = photon_auth.register_user_if_absent(
- dashboard_id, secret, phone_number=phone, first_name=args.first_name,
- last_name=args.last_name, email=args.email)
- except ValueError as e:
- print(f" invalid phone number: {e}", file=sys.stderr)
- return 1
- except Exception as e:
- print(f" user registration failed: {e}", file=sys.stderr)
- return 1
- print(" ✓ phone registered" if created else " ✓ phone already registered")
- registered_phone = phone
- registered_user_id = user.get("id")
- # The number to text the agent is the user's assigned line ("TEXTS ON"); shared-number
- # plans have no dedicated /lines entry.
- agent_number = photon_auth.user_assigned_line(user) or _lookup_imessage_line(token, dashboard_id)
- # Opt-in gate: Photon only routes a number whose user row carries meta.opt_in, which the
- # service sets once the human texts the assigned line from their phone (the API cannot
- # set it). Name the line and wait for the opt-in; a re-run on an opted-in row passes.
- if photon_auth.user_opted_in(user):
- routing_live = True
- print(" ✓ number is opted in — routing is live")
- elif not agent_number: # nothing to text yet, so a wait could never end in an opt-in
- routing_live = False
- print(f" ⚠ No iMessage line is assigned to {phone} yet — skipping the opt-in wait.\n"
- f" Once the Photon dashboard shows your line, text it once from {phone},\n"
- " then check with `hermes photon status`.")
- else:
- opted = _wait_for_opt_in(dashboard_id, secret, phone, agent_number)
- routing_live = opted is not None
- agent_number = photon_auth.user_assigned_line(opted) or agent_number
- # Otherwise the gateway denies the operator's own inbound and has no cron home space.
- _autoconfigure_access(phone)
- # 5. Surface the agent's iMessage number.
- if not agent_number and not phone: # the phone path already looked the line up
- agent_number = _lookup_imessage_line(token, dashboard_id)
- if agent_number:
- print("\n" + "\n".join((
- color("┌─ Your agent's iMessage number ───────────────────────────────", Colors.GREEN),
- color("│ 📱 ", Colors.GREEN) + color(str(agent_number), Colors.GREEN, Colors.BOLD),
- color("│ Text this number from your phone to talk to your agent.", Colors.GREEN),
- color("└──────────────────────────────────────────────────────────────", Colors.GREEN))))
- else:
- print(" No iMessage line assigned yet — check the Photon dashboard.")
- if registered_phone:
- try:
- photon_auth.store_user_numbers(
- phone_number=registered_phone, assigned_phone_number=agent_number,
- user_id=str(registered_user_id) if registered_user_id else None, dashboard_project_id=dashboard_id)
- except Exception as e:
- print(f" (could not save Photon status metadata: {e})", file=sys.stderr)
- # 6. Sidecar deps (spectrum-ts).
- if args.skip_sidecar_install:
- print("[5/5] Skipping sidecar npm install (--skip-sidecar-install)")
- else:
- print("[5/5] Installing Node sidecar deps (spectrum-ts)...")
- rc = _install_sidecar()
- if rc != 0:
- return rc
- # 7. Enable the platform in config.yaml, or the channel silently stays offline.
- try:
- from hermes_cli.config import write_platform_config_field
- write_platform_config_field("photon", "enabled", True, raw=True)
- print(" ✓ photon platform enabled in config.yaml")
- except Exception as e:
- print(f" (could not enable Photon in config: {e})", file=sys.stderr)
- if not phone: # saved, but nothing can route until a number is registered and opted in
- print("\n⚠ Photon setup saved, but iMessage routing is NOT live: no phone number is registered.\n"
- " Finish with: hermes photon setup --phone +15551234567")
- return 0
- if not routing_live: # saved, but not "complete": the gateway cannot reach this number yet
- print(f"\n⚠ Photon setup saved, but iMessage routing is NOT live: text {agent_number or 'your assigned line'} "
- f"once from {phone}.\n Check with `hermes photon status`; start the gateway once it shows opted in.")
- return 0
- print("\n✓ Photon setup complete.\n Start the gateway: hermes gateway start")
- return 0
- def _lookup_imessage_line(token: str, dashboard_id: str) -> Optional[str]:
- """The project's dedicated iMessage line (fallback when the user row names none)."""
- try:
- line = photon_auth.get_imessage_line(token, dashboard_id)
- except (photon_auth.httpx.HTTPError, RuntimeError, ValueError, AttributeError, TypeError) as e: # transport / status / bad or misshapen JSON
- print(f" (could not fetch the assigned line: {e})", file=sys.stderr)
- return None
- return line.get("phoneNumber") if line else None
- _OPT_IN_WAIT_S = 300
- def _wait_for_opt_in(dashboard_id: str, secret: str, phone: str, agent_number: Optional[str]) -> Optional[dict]:
- """Print the opt-in step and, on a TTY, wait (bounded) for it to land. Returns the
- opted-in user row, or None when skipped, timed out or interrupted."""
- line_hint = agent_number or "the line Photon assigns to your number"
- print("\n" + color(" One manual step: opt in by texting your agent", Colors.CYAN, Colors.BOLD))
- print(" Your number only enters iMessage routing after it has messaged the line\n"
- f" Photon assigned to it:\n 1. Open Messages on {phone}.\n"
- f" 2. Text {line_hint} — one message of any content is enough.")
- if not sys.stdin.isatty(): # scripted setup / CI: nobody can answer the poll
- print(" Non-interactive run — skipping the opt-in wait. Verify later with `hermes photon status`.")
- return None
- print(f" Setup waits here (up to {_OPT_IN_WAIT_S // 60} minutes) and continues once the opt-in lands.\n"
- " (Ctrl-C to skip — re-running setup resumes where it left off.)")
- def _on_waiting(attempt: int) -> None:
- if attempt % 6 == 0:
- print(" ... still waiting for your message to land")
- try:
- opted = photon_auth.wait_for_opted_in_user(
- dashboard_id, secret, phone, timeout_s=_OPT_IN_WAIT_S, on_waiting=_on_waiting)
- why = f"No opt-in seen within {_OPT_IN_WAIT_S // 60} minutes."
- except KeyboardInterrupt:
- opted, why = None, "Wait skipped (Ctrl-C)."
- print()
- if opted is None:
- print(f" ⚠ {why}\n {phone} is not opted in yet: text {line_hint} once from it, then re-run\n"
- " `hermes photon setup` (it resumes where it left off).")
- return None
- print(" ✓ opt-in landed — routing is live")
- return opted
- def _autoconfigure_access(phone: str) -> None:
- """Set PHOTON_ALLOWED_USERS and PHOTON_HOME_CHANNEL to the operator's number, each only
- when unset so a hand-tuned value is never clobbered on re-run."""
- try:
- from hermes_cli.config import get_env_value, save_env_value
- except ImportError:
- return
- for key, label in (("PHOTON_ALLOWED_USERS", "allowlisted your number"),
- ("PHOTON_HOME_CHANNEL", "set your DM as the cron home channel")):
- try:
- if get_env_value(key):
- print(f" {key} already set — leaving it as-is.")
- continue
- save_env_value(key, phone)
- print(f" ✓ {label} ({key})")
- except Exception as e:
- print(f" could not set {key}: {e}", file=sys.stderr)
- def _cmd_status(_args: argparse.Namespace) -> int:
- phone, assigned = photon_auth.load_user_numbers()
- if not (phone and assigned):
- spectrum_id, project_secret = photon_auth.load_project_credentials()
- if spectrum_id and project_secret:
- try:
- photon_auth.refresh_user_numbers(spectrum_id, project_secret)
- except Exception as e:
- print(f" (could not refresh Photon user numbers: {e})", file=sys.stderr)
- # auth.print_credential_summary's emit callback is the only sink that sees
- # credential-derived strings (keeps cli.py taint-free for CodeQL).
- photon_auth.print_credential_summary(print)
- node_bin = find_node_executable("node")
- print(f" node binary : {node_bin or '✗ missing (install Node 18+)'}")
- print(f" sidecar deps : {'✓ installed' if sidecar_deps_installed() else '✗ run `hermes photon install-sidecar`'}")
- print(f" telemetry : {'on' if _telemetry_enabled() else 'off'} (`hermes photon telemetry on|off`)")
- photon_auth.print_routing_status(print)
- return 0
- def _telemetry_enabled() -> bool:
- """PHOTON_TELEMETRY from env / ~/.hermes/.env; truthy set mirrors the sidecar's."""
- try:
- from hermes_cli.config import get_env_value
- raw = get_env_value("PHOTON_TELEMETRY")
- except ImportError:
- raw = os.getenv("PHOTON_TELEMETRY")
- return (raw or "").strip().lower() in ("1", "true", "yes", "on")
- def _cmd_telemetry(args: argparse.Namespace) -> int:
- state = getattr(args, "state", None)
- if state is None:
- print(f"Photon telemetry: {'on' if _telemetry_enabled() else 'off'}")
- print(" Toggle with `hermes photon telemetry on` / `hermes photon telemetry off`.")
- return 0
- try:
- from hermes_cli.config import save_env_value
- save_env_value("PHOTON_TELEMETRY", "true" if state == "on" else "false")
- except Exception as e:
- print(f"could not save PHOTON_TELEMETRY: {e}", file=sys.stderr)
- return 1
- print(f"✓ Spectrum telemetry turned {state} (PHOTON_TELEMETRY in ~/.hermes/.env)")
- print(" Restart the gateway for the sidecar to pick it up: hermes gateway restart")
- return 0
- def _install_sidecar() -> int:
- import pm
- try:
- npm = find_node_executable("npm")
- env = with_hermes_node_path()
- if npm is None:
- env = pm.ensure("npm", explicit=True).env
- installed = pm.installed_package("npm")
- if installed is None or installed.binary is None:
- raise pm.InstallError("npm", "ensured but no selected binary was recorded")
- npm = str(installed.binary)
- except pm.InstallError as exc:
- print(f"Could not prepare Photon dependencies: {exc}", file=sys.stderr)
- return 1
- # spectrum-ts is pinned exactly (the SDK ships breaking majors); upgrades are deliberate —
- # never `@latest` (see README "Upgrading spectrum-ts"). `npm ci` installs the lockfile
- # verbatim; `npm install` is the fallback for a missing/drifted lockfile.
- print(f" $ cd {_sidecar_dir()} && {npm} ci")
- def _run(verb: str) -> subprocess.CompletedProcess:
- # stdout streams to the terminal; stderr is captured so the failure reason can be
- # persisted for check_requirements() to surface later.
- proc = subprocess.run(
- [npm, verb], stdin=subprocess.DEVNULL, cwd=str(_sidecar_dir()), check=False, stderr=subprocess.PIPE, text=True, env=env)
- if proc.stderr:
- print(proc.stderr, end="", file=sys.stderr)
- return proc
- proc = _run("ci")
- if proc.returncode != 0:
- print(f" npm ci failed — falling back to: {npm} install")
- proc = _run("install")
- error = (proc.stderr or "").strip()[:_NPM_ERROR_LOG_MAX_CHARS] # bounded to what check_requirements surfaces
- if proc.returncode != 0:
- print("npm install failed", file=sys.stderr)
- with contextlib.suppress(OSError):
- if proc.returncode == 0:
- _npm_error_log().unlink()
- elif error:
- _npm_error_log().write_text(error, encoding="utf-8")
- return proc.returncode
- _COMMANDS = {
- "setup": _cmd_setup, "status": _cmd_status, "install-sidecar": lambda _args: _install_sidecar(),
- "telemetry": _cmd_telemetry}
- def gateway_setup() -> None:
- """Run Photon first-time setup from the unified `hermes gateway setup` wizard (same flow
- as ``hermes photon setup``; phone is prompted when stdin is a TTY)."""
- _cmd_setup(argparse.Namespace(
- photon_command="setup", project_name=None, phone=None, first_name=None, last_name=None,
- email=None, no_browser=False, skip_sidecar_install=False))
- def _prompt(prompt: str, *, secret: bool = False) -> str:
- if not sys.stdin.isatty():
- return ""
- try:
- return (getpass.getpass(prompt) if secret else input(prompt)).strip()
- except (KeyboardInterrupt, EOFError):
- print()
- return ""
|