booking-agent-cli 0.1.0__py3-none-any.whl

booking_agent_cli/commands/lowlevel.py

@@ -0,0 +1,163 @@
+"""Low-level operator commands.
+
+These bypass the flow engine and do NOT read or mutate ``.usp-session.json``.
+Documented as repair / debug tools only.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+from datetime import datetime, timedelta, timezone
+from typing import List, Optional
+
+import typer
+
+from .. import config_loader
+from ..runtime import resolve_backend
+
+# search ---------------------------------------------------------------------
+
+search_app = typer.Typer(help="Low-level: search the USP registry (no session writes).")
+
+
+@search_app.callback(invoke_without_command=True)
+def search(
+    ctx: typer.Context,
+    query: str = typer.Option(..., "--query", "-q"),
+    location: Optional[str] = typer.Option(
+        None,
+        "--location",
+        help="Optional geo filter as latitude,longitude",
+    ),
+    radius_km: Optional[float] = typer.Option(
+        None,
+        "--radius-km",
+        help="Search radius in km when --location is set",
+    ),
+    vertical: Optional[List[str]] = typer.Option(
+        None,
+        "--vertical",
+        help="Repeatable registry vertical filter; omit to search all verticals",
+    ),
+    desired_at: Optional[List[str]] = typer.Option(None, "--desired-at"),
+    desired_from: Optional[List[str]] = typer.Option(None, "--desired-from"),
+    desired_range: Optional[List[str]] = typer.Option(None, "--desired-range"),
+    prefer_sooner_availability_slots: Optional[bool] = typer.Option(
+        None,
+        "--prefer-sooner-availability-slots/--no-prefer-sooner-availability-slots",
+    ),
+) -> None:
+    if ctx.invoked_subcommand is not None:
+        return
+    config_loader.load()
+    backend = resolve_backend()
+
+    async def _go():
+        from booking_agent.headless import (
+            build_search_intent,
+            build_desired_service_time_preferences,
+            discover_services,
+            parse_service_search_location,
+            parse_service_verticals,
+        )
+        from booking_agent.models.platform import ServiceSearchLocation
+
+        loc = None
+        if location and location.strip():
+            parsed = parse_service_search_location(location)
+            if radius_km is not None:
+                loc = ServiceSearchLocation(
+                    coordinates=parsed.coordinates,
+                    radius_km=radius_km,
+                )
+            else:
+                loc = parsed
+        time_preferences = build_desired_service_time_preferences(
+            desired_at=desired_at,
+            desired_from=desired_from,
+            desired_range=desired_range,
+        )
+        return await discover_services(
+            backend,
+            build_search_intent(
+                query=query,
+                location=loc,
+                verticals=parse_service_verticals(vertical),
+                desired_service_time_ranges=time_preferences or None,
+                prefer_sooner_availability_slots=prefer_sooner_availability_slots,
+            ),
+        )
+
+    try:
+        services = asyncio.run(_go())
+    except ValueError as exc:
+        typer.echo(json.dumps({"error": str(exc)}), err=True)
+        raise typer.Exit(code=1) from exc
+    from ..catalog import discover_summary_from_service, sort_discover_summaries_by_rank
+
+    summaries = []
+    for rank, service in enumerate(services):
+        row = discover_summary_from_service(service)
+        if row.get("search_rank") is None:
+            row["search_rank"] = rank
+        summaries.append(row)
+    typer.echo(json.dumps(sort_discover_summaries_by_rank(summaries), indent=2))
+
+
+# profile --------------------------------------------------------------------
+
+profile_app = typer.Typer(help="Low-level: profile resolution.")
+
+
+@profile_app.command("resolve")
+def profile_resolve(
+    profile_url: str = typer.Option(..., "--profile-url"),
+) -> None:
+    config_loader.load()
+    backend = resolve_backend()
+
+    async def _go():
+        return await backend.resolve_profile(profile_url)
+
+    profile = asyncio.run(_go())
+    typer.echo(json.dumps({
+        "version": profile.version,
+        "rest_endpoint": profile.rest_endpoint,
+        "business": profile.business.model_dump(by_alias=True),
+        "has_catalog": profile.has_catalog,
+        "has_availability": profile.has_availability,
+        "has_bookings": profile.has_bookings,
+    }, indent=2))
+
+
+# availability ---------------------------------------------------------------
+
+availability_app = typer.Typer(help="Low-level: query availability.")
+
+
+@availability_app.command("query")
+def availability_query(
+    profile_url: str = typer.Option(..., "--profile-url"),
+    service_id: str = typer.Option(..., "--service-id"),
+    start: Optional[str] = typer.Option(None, "--from"),
+    end: Optional[str] = typer.Option(None, "--to"),
+) -> None:
+    config_loader.load()
+    now = datetime.now(timezone.utc)
+    window_from = start or (now + timedelta(days=1)).replace(hour=0, minute=0, second=0, microsecond=0).isoformat()
+    window_to = end or (now + timedelta(days=14)).replace(hour=23, minute=59, second=59, microsecond=0).isoformat()
+    backend = resolve_backend()
+
+    async def _go():
+        from booking_agent.headless import query_availability_with_quirk
+        profile = await backend.resolve_profile(profile_url)
+        slots = await query_availability_with_quirk(
+            backend, profile, service_id, window_from, window_to
+        )
+        return slots
+
+    slots = asyncio.run(_go())
+    typer.echo(json.dumps(
+        [{"slot_id": s.id, "start": s.start, "end": s.end, "duration": s.duration} for s in slots],
+        indent=2,
+    ))

booking_agent_cli/commands/runtime.py

@@ -0,0 +1,46 @@
+"""``booking-agent runtime``: prepare the folders this runtime keeps its state in."""
+from __future__ import annotations
+
+from typing import List
+
+import typer
+
+from ..output import AgentOutput, emit
+from ..runtime_prepare import PrepareError, prepare
+
+app = typer.Typer(help="Runtime setup for agents whose filesystem resets between conversations.")
+
+
+@app.command("prepare")
+def runtime_prepare(
+    persistent_root: str = typer.Option(
+        ...,
+        "--persistent-root",
+        help="Absolute folder that survives between conversations in this runtime",
+    ),
+    link: List[str] = typer.Option(
+        [],
+        "--link",
+        help="Extra RUNTIME_PATH=PERSISTENT_PATH folder to keep (relative PERSISTENT_PATH is under the root)",
+    ),
+) -> None:
+    """Link Booking Agent state and the Link sign-in into a folder that outlives this runtime."""
+    try:
+        links = prepare(persistent_root, link)
+    except (PrepareError, OSError) as exc:
+        emit(AgentOutput(
+            phase="INIT",
+            prompt=(
+                "Persistence was not set up. Continue the booking without it; state from "
+                "this conversation may not survive a restart."
+            ),
+            next_command="booking-agent flow sessions list",
+            data={"error": {"code": "runtime_prepare_failed", "message": str(exc)}},
+        ))
+        raise typer.Exit(code=1)
+    emit(AgentOutput(
+        phase="INIT",
+        prompt="Booking Agent state and the Link sign-in now live in the persistent folder.",
+        next_command="booking-agent flow sessions list",
+        data={"links": links},
+    ))

booking_agent_cli/config_loader.py

@@ -0,0 +1,108 @@
+"""Load env files into the process for one command, in priority order.
+
+Highest first: the process environment, ``~/.booking-agent/.env``, ``./.env``. Each
+layer only fills names a higher layer left unset. The shipped ``defaults.env`` is the
+lowest layer and is read through ``booking_agent.settings`` instead of being copied
+into the environment.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from dotenv import dotenv_values
+
+from booking_agent import settings
+
+SOURCE_PROCESS = "process environment"
+SOURCE_USER = "user .env"
+SOURCE_FOLDER = "folder .env"
+SOURCE_SHIPPED = "shipped default"
+
+# Names this module put into os.environ, with the value and the layer they came from.
+_applied: Dict[str, Tuple[str, str]] = {}
+_loaded_files: List[Tuple[str, Path]] = []
+_ignored_runtime: List[Tuple[str, Path, str]] = []
+
+
+@dataclass(frozen=True)
+class Layer:
+    source: str
+    path: Path
+
+
+def user_env_path() -> Path:
+    return settings.booking_agent_home() / ".env"
+
+
+def layers() -> List[Layer]:
+    return [
+        Layer(SOURCE_USER, user_env_path()),
+        Layer(SOURCE_FOLDER, Path.cwd() / ".env"),
+    ]
+
+
+def reset() -> None:
+    """Remove every value this module put into the environment."""
+    for name, (value, _source) in _applied.items():
+        if os.environ.get(name) == value:
+            del os.environ[name]
+    _applied.clear()
+    _loaded_files.clear()
+    _ignored_runtime.clear()
+
+
+def load() -> None:
+    """Re-apply the layers for this command. Safe to call more than once per process."""
+    reset()
+    for layer in layers():
+        if not layer.path.is_file():
+            continue
+        _loaded_files.append((layer.source, layer.path))
+        for name, value in dotenv_values(layer.path).items():
+            if name in settings.RUNTIME_ONLY:
+                _ignored_runtime.append((layer.source, layer.path, name))
+                continue
+            if value is None or name in os.environ:
+                continue
+            os.environ[name] = value
+            _applied[name] = (value, layer.source)
+
+
+def source_of(name: str) -> str:
+    if name in _applied and os.environ.get(name) == _applied[name][0]:
+        return _applied[name][1]
+    if name in os.environ:
+        return SOURCE_PROCESS
+    if settings.shipped_default(name) is None:
+        return "unset"
+    return SOURCE_SHIPPED
+
+
+def process_value(name: str) -> Optional[str]:
+    """The value the process started with; a value an env file supplied is never returned."""
+    if name in _applied and os.environ.get(name) == _applied[name][0]:
+        return None
+    return os.environ.get(name)
+
+
+def loaded_files() -> List[Tuple[str, Path]]:
+    return list(_loaded_files)
+
+
+def unknown_keys() -> List[Tuple[str, Path, str]]:
+    """Names in the loaded env files that nothing reads (for example renamed variables)."""
+    known = settings.known_names()
+    out = []
+    for source, path in _loaded_files:
+        for name in dotenv_values(path):
+            if name not in known:
+                out.append((source, path, name))
+    return out
+
+
+def ignored_runtime_keys() -> List[Tuple[str, Path, str]]:
+    """Per-process names found in an env file. They are never read from one."""
+    return list(_ignored_runtime)

booking_agent_cli/engine.py

@@ -0,0 +1,168 @@
+"""Flow state machine (Section 6 of PLAN).
+
+The engine reads + writes ``.usp-session.json`` via session.py. Gate
+helpers raise ``GateError`` so command handlers can emit a uniform
+agent-facing JSON error and exit 1.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .session import BUYER_SOURCE_LINKCLI, Buyer, Session
+
+
+class GateError(Exception):
+    """Raised when a hard gate has not been satisfied."""
+
+    def __init__(self, code: str, message: str, *, next_command: str | None = None):
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.next_command = next_command
+
+
+@dataclass(frozen=True)
+class TransitionRule:
+    """Allowed phase progression check (advisory; used by validate)."""
+
+    name: str
+
+
+def require_phase(session: Session, *allowed: str, code: str, next_command: str | None = None) -> None:
+    if session.flow_phase not in allowed:
+        raise GateError(
+            code,
+            f"Wrong phase '{session.flow_phase}'. Expected one of: {', '.join(allowed)}.",
+            next_command=next_command,
+        )
+
+
+def require_business(session: Session) -> None:
+    if not session.business.profile_url:
+        raise GateError(
+            "no_business",
+            "No business selected. Run `booking-agent flow business use --profile-url ...` "
+            "or `booking-agent flow discover`.",
+            next_command="booking-agent flow discover",
+        )
+
+
+def require_calendar_gate(session: Session) -> None:
+    if not session.calendar_gate_completed:
+        raise GateError(
+            "calendar_gate_not_completed",
+            "Calendar gate not completed. Ask the user about calendar conflict "
+            "checking, then run `booking-agent flow calendar ask|skip|connect`.",
+            next_command="booking-agent flow calendar ask",
+        )
+
+
+def require_link_auth_gate(session: Session) -> None:
+    if not session.link_auth_gate_completed:
+        raise GateError(
+            "link_auth_gate_not_completed",
+            "Link wallet authentication not completed. Run "
+            "`booking-agent flow link-auth connect`, post the sign-in link, and start "
+            "`booking-agent flow link-auth poll` in the background in the same turn.",
+            next_command="booking-agent flow link-auth connect",
+        )
+
+
+def require_checkout_prereq(session: Session) -> None:
+    if session.checkout_prereq_completed:
+        return
+    if getattr(session, "payment_route", None) in ("free", "at_service"):
+        return
+    raise GateError(
+        "checkout_prereq_not_completed",
+        "Checkout prerequisites were not completed. Run the checkout-mode "
+        "orchestrator before the calendar gate.",
+        next_command="booking-agent flow use-ucp-checkout-mode",
+    )
+
+
+def require_slot_selected(session: Session) -> None:
+    if not session.slot_id or not session.slot_user_confirmed:
+        raise GateError(
+            "slot_not_selected",
+            "No user-confirmed slot. Present `slots_presented` to the user, "
+            "wait for their pick, then call `booking-agent flow slots select`.",
+            next_command="booking-agent flow slots list",
+        )
+
+
+def require_buyer_from_link_cli(session: Session) -> None:
+    if session.buyer_source != BUYER_SOURCE_LINKCLI:
+        raise GateError(
+            "buyer_not_from_link_cli",
+            "Buyer must come from `link-cli user-info retrieve`. Placeholders, "
+            "hand-entered values, and other sources are rejected.",
+            next_command="booking-agent flow buyer resolve",
+        )
+    email = session.buyer.email or ""
+    if email and not email.lower().endswith("@example.com"):
+        return
+    from .link_cli import (
+        LinkCliUserInfoError,
+        buyer_fields_from_user_info,
+        retrieve_user_info,
+    )
+
+    try:
+        payload = retrieve_user_info()
+    except LinkCliUserInfoError as e:
+        raise GateError(
+            e.code,
+            e.message,
+            next_command="booking-agent flow buyer resolve",
+        ) from e
+    name, email, phone = buyer_fields_from_user_info(payload)
+    if not email or email.lower().endswith("@example.com"):
+        raise GateError(
+            "buyer_email_invalid",
+            "Buyer email is missing or uses an @example.com placeholder.",
+            next_command="booking-agent flow buyer resolve",
+        )
+    session.buyer = Buyer(name=name, email=email, phone=phone)
+
+
+def transition(session: Session, *, to: str) -> None:
+    """In-place phase update with the previous phase implicit."""
+    session.flow_phase = to
+
+
+def recommend_next(session: Session) -> str | None:
+    """Best-effort suggestion for the agent's next command."""
+    phase = session.flow_phase
+    pending = session.pending_booking_attempt
+    if isinstance(pending, dict) and isinstance(pending.get("retry_command"), str):
+        return pending["retry_command"]
+    if phase == "CONFIRMED" and session.reschedule_original_slot_id is not None:
+        if session.reschedule_slot_id:
+            return "booking-agent flow reschedule apply --user-confirmed"
+        if session.reschedule_slots:
+            return "booking-agent flow reschedule select --slot-id <id> --user-confirmed"
+        return "booking-agent flow reschedule availability"
+    if phase == "BUSINESS_SELECTED":
+        return "booking-agent flow use-ucp-checkout-mode"
+    if phase == "BOOKED":
+        return (
+            "booking-agent flow pay request --payment-method-id <id>"
+        )
+    if phase == "PAYMENT_PENDING":
+        sr = session.payment.spend_request_id
+        if sr:
+            return f"booking-agent flow pay ucp-complete --spend-request-id {sr}"
+        return "booking-agent flow pay ucp-complete"
+    table = {
+        "INIT": "booking-agent flow prereq check",
+        "PREREQ_OK": "booking-agent flow discover",
+        "CALENDAR_GATE": "booking-agent flow availability",
+        "AVAILABILITY_QUERIED": "booking-agent flow slots list",
+        "SLOTS_PRESENTED": "booking-agent flow slots select --slot-id <id>",
+        "SLOT_SELECTED": "booking-agent flow link-auth connect",
+        "BUYER_RESOLVED": "booking-agent flow book",
+        "CONFIRMED": None,
+        "FAILED": None,
+    }
+    return table.get(phase)

booking_agent_cli/flow_timings.py

@@ -0,0 +1,34 @@
+"""Persist per-step flow timings on the session and surface them in CLI output."""
+from __future__ import annotations
+
+from typing import Any, Dict
+
+from booking_agent.step_timing import drain_pending_timings, StepTiming
+
+from .session import Session
+
+
+def apply_pending_timings(session: Session) -> None:
+    """Merge drained step timings into the session record."""
+    for timing in drain_pending_timings():
+        if timing.step.startswith("human_gate:"):
+            gate = timing.step.split(":", 1)[1]
+            session.human_gate_timings[gate] = round(timing.human_gate_ms, 1)
+        else:
+            session.flow_timings[timing.step] = timing.to_dict()
+
+
+def timings_data(session: Session) -> Dict[str, Any]:
+    """Payload fragment for AgentOutput ``data``."""
+    return {
+        "flow_timings": dict(session.flow_timings),
+        "human_gate_timings": dict(session.human_gate_timings),
+    }
+
+
+def record_timing_on_session(session: Session, timing: StepTiming) -> None:
+    if timing.step.startswith("human_gate:"):
+        gate = timing.step.split(":", 1)[1]
+        session.human_gate_timings[gate] = round(timing.human_gate_ms, 1)
+    else:
+        session.flow_timings[timing.step] = timing.to_dict()