guzli-cli 0.2.0__py3-none-any.whl

guzli/commands/auth.py

@@ -0,0 +1,502 @@
+from __future__ import annotations
+
+import argparse
+import contextlib
+import sys
+
+from guzli.auth import AuthSelector
+from guzli.commands.common import add_json_flag as _add_json_flag
+from guzli.commands.common import print_error as _print_error
+from guzli.config import DEFAULT_BASE_URL, EnvironmentConfig
+from guzli.config_store import ConfigStore, StoredProfile, mask_secret
+from guzli.errors import ApiError, ConfigError, ValidationError
+from guzli.http_client import HttpClient
+from guzli.oauth_callback import OAuthCallbackConfig, OAuthLoopbackCallbackServer
+from guzli.runtime import RuntimeContext
+from guzli.services import CliAuthService
+
+
+def handle_auth_login(args: argparse.Namespace) -> None:
+    mode = getattr(args, "login_mode", "api-key")
+    if mode == "oauth":
+        handle_auth_login_oauth(args)
+        return
+    handle_auth_login_api_key(args)
+
+
+def handle_auth_login_api_key(args: argparse.Namespace) -> None:
+    import getpass
+
+    store = ConfigStore()
+    profile_name = (args.profile_name or args.profile or "default").strip() or "default"
+    existing = store.get_profile(profile_name)
+    base_url = args.login_base_url or (existing.base_url if existing else None) or DEFAULT_BASE_URL
+    api_key = args.login_api_key
+    agent_id = args.login_agent_id
+    organization_id = args.login_organization_id
+
+    interactive = sys.stdin.isatty() and not (api_key and agent_id)
+    if interactive:
+        print(f"Logging in to profile '{profile_name}'.")
+        prompt_base = f"Base URL [{base_url}]: "
+        typed_base = input(prompt_base).strip()
+        if typed_base:
+            base_url = typed_base
+        if not api_key:
+            api_key = getpass.getpass("API key (input hidden): ").strip()
+        if not agent_id:
+            default_agent = existing.agent_id if existing else ""
+            suffix = f" [{default_agent}]" if default_agent else ""
+            typed_agent = input(f"Agent ID{suffix}: ").strip()
+            agent_id = typed_agent or default_agent
+        if not organization_id:
+            default_org = existing.organization_id if existing else ""
+            suffix = f" [{default_org}]" if default_org else ""
+            typed_org = input(f"Organization ID{suffix}: ").strip()
+            organization_id = typed_org or default_org
+
+    if not api_key:
+        raise ValidationError("--api-key is required (or run interactively)")
+    if not agent_id:
+        raise ValidationError("--agent-id is required (or run interactively)")
+
+    profile = StoredProfile(
+        name=profile_name,
+        base_url=base_url,
+        api_key=api_key,
+        bearer_token=existing.bearer_token if existing else None,
+        refresh_handle=existing.refresh_handle if existing else None,
+        access_token_expires_at=existing.access_token_expires_at if existing else None,
+        cli_session_id=existing.cli_session_id if existing else None,
+        agent_id=agent_id,
+        organization_id=(organization_id or (existing.organization_id if existing else None)),
+        default_number_pool_id=existing.default_number_pool_id if existing else None,
+        timeout_seconds=existing.timeout_seconds if existing else None,
+    )
+    store.save_profile(profile, set_active=not args.no_activate)
+    print(f"Saved profile '{profile_name}' to {store.path}")
+    if not args.no_activate:
+        print(f"Active profile: {profile_name}")
+
+
+def handle_auth_login_oauth(args: argparse.Namespace) -> None:
+    """Browser-based OAuth login via the engine's /api/public/v2/auth/cli/oauth/* endpoints.
+    Opens a localhost callback listener, sends the user to the engine's authorization URL
+    (which delegates to Supabase OAuth under the hood), captures the returned state+code,
+    exchanges for an engine-issued access token + opaque refresh handle, and persists
+    everything to the named profile."""
+    import os
+    import platform
+    import socket
+    import webbrowser
+
+    store = ConfigStore()
+    profile_name = (args.profile_name or args.profile or "default").strip() or "default"
+    existing = store.get_profile(profile_name)
+    base_url = args.login_base_url or (existing.base_url if existing else None) or DEFAULT_BASE_URL
+    organization_id = (
+        args.login_organization_id
+        or os.getenv("GUZLI_ORGANIZATION_ID")
+        or (existing.organization_id if existing else None)
+    )
+    if not organization_id:
+        raise ValidationError(
+            "--organization-id is required for --mode oauth. "
+            "Pass --organization-id <uuid> or set GUZLI_ORGANIZATION_ID."
+        )
+
+    # Build a bootstrap HttpClient with no auth — start/exchange are unauthenticated.
+    bootstrap_client = HttpClient(
+        base_url=base_url,
+        auth_selector=AuthSelector(api_key_auth=None, bearer_auth=None),
+        timeout_seconds=30,
+        agent_id=None,
+        organization_id=None,
+    )
+    cli_auth = CliAuthService(bootstrap_client)
+
+    callback = OAuthLoopbackCallbackServer(
+        OAuthCallbackConfig.from_inputs(port=args.login_callback_port),
+        _OAUTH_SUCCESS_HTML,
+    )
+    redirect_uri = callback.redirect_uri
+    callback.start()
+    try:
+        metadata = {
+            "hostname": socket.gethostname(),
+            "os": f"{platform.system()} {platform.release()}",
+            "version": _cli_version(),
+        }
+        start_resp = cli_auth.start(
+            redirect_uri=redirect_uri,
+            client_display_name=args.login_client_name,
+            client_metadata=metadata,
+        )
+        if not isinstance(start_resp, dict) or "authorization_url" not in start_resp:
+            raise ApiError("OAuth start response missing authorization_url")
+        auth_url = str(start_resp["authorization_url"])
+
+        print()
+        print("Opening your browser to authenticate with Guzli...")
+        print("If it does not open automatically, paste this URL:")
+        print(f"  {auth_url}")
+        print()
+        with contextlib.suppress(Exception):
+            webbrowser.open(auth_url)
+
+        timeout_seconds = callback.config.timeout_seconds
+        print(f"Waiting for callback on {redirect_uri} (timeout: {timeout_seconds}s)...")
+        captured = callback.wait_for_result()
+    finally:
+        callback.close()
+
+    if captured.error:
+        raise ConfigError(
+            f"OAuth login failed: {captured.error} "
+            f"({captured.error_description or 'no description'})"
+        )
+    if not captured.state or not captured.code:
+        raise ConfigError("OAuth callback was missing state or code parameters.")
+
+    print("Exchanging authorization code for engine access token...")
+    exchange_resp = cli_auth.exchange(
+        state=captured.state,
+        code=captured.code,
+        redirect_uri=redirect_uri,
+        organization_id=organization_id,
+    )
+    if not isinstance(exchange_resp, dict) or "access_token" not in exchange_resp:
+        raise ApiError("OAuth exchange response missing access_token")
+
+    session = (
+        exchange_resp.get("session", {}) if isinstance(exchange_resp.get("session"), dict) else {}
+    )
+    profile = StoredProfile(
+        name=profile_name,
+        base_url=base_url,
+        api_key=args.login_api_key or (existing.api_key if existing else None),
+        bearer_token=str(exchange_resp["access_token"]),
+        refresh_handle=str(exchange_resp["refresh_handle"]),
+        access_token_expires_at=str(exchange_resp.get("expires_at") or ""),
+        cli_session_id=str(session.get("id") or "") or None,
+        agent_id=args.login_agent_id or (existing.agent_id if existing else None),
+        organization_id=organization_id,
+        default_number_pool_id=existing.default_number_pool_id if existing else None,
+        timeout_seconds=existing.timeout_seconds if existing else None,
+    )
+    store.save_profile(profile, set_active=not args.no_activate)
+    print()
+    print(f"Logged in. Saved profile '{profile_name}' to {store.path}")
+    if not args.no_activate:
+        print(f"Active profile: {profile_name}")
+    print(f"Session id:    {session.get('id') or '(unknown)'}")
+    print(f"User:          {session.get('user_email') or session.get('user_id') or '(unknown)'}")
+    print(f"Expires at:    {exchange_resp.get('expires_at') or '(unknown)'}")
+    print("Auto-refreshes for up to 30 days; sign out anytime with `guzli auth logout`.")
+
+
+def _cli_version() -> str:
+    try:
+        from guzli import __version__
+
+        return str(__version__)
+    except Exception:
+        return "unknown"
+
+
+_OAUTH_SUCCESS_HTML = """<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Guzli CLI — logged in</title>
+  <style>
+    body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+           display: flex; align-items: center; justify-content: center; min-height: 100vh;
+           margin: 0; color: #1a1a1a; background: #fafafa; }
+    .card { max-width: 420px; padding: 32px; background: white; border-radius: 12px;
+            box-shadow: 0 1px 3px rgba(0,0,0,0.08); text-align: center; }
+    h1 { margin: 0 0 12px; font-size: 20px; }
+    p { margin: 0; color: #555; font-size: 14px; line-height: 1.5; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>You are logged in.</h1>
+    <p>Return to your terminal — the Guzli CLI has your session.<br>You can close this tab.</p>
+  </div>
+</body>
+</html>
+"""
+
+
+def handle_auth_logout(args: argparse.Namespace) -> None:
+    store = ConfigStore()
+    if args.all:
+        # Best-effort: revoke every OAuth session we have a refresh_handle for before nuking.
+        for name in store.list_profiles():
+            profile = store.get_profile(name)
+            if profile and profile.refresh_handle and profile.base_url:
+                _try_revoke_oauth_session(profile.base_url, profile.refresh_handle, profile.name)
+        removed = store.clear_all()
+        print("Removed config file" if removed else "No config file to remove")
+        return
+    profile_name = args.profile_name or args.profile or store.active_profile_name()
+    if not profile_name:
+        print("No active profile to log out of")
+        return
+    profile = store.get_profile(profile_name)
+    if profile and profile.refresh_handle and profile.base_url:
+        _try_revoke_oauth_session(profile.base_url, profile.refresh_handle, profile.name)
+    if args.delete_profile:
+        removed = store.delete_profile(profile_name)
+        if removed:
+            print(f"Removed profile '{profile_name}'")
+        else:
+            print(f"Profile '{profile_name}' was not present")
+        return
+    if profile:
+        store.save_profile(_profile_without_oauth_session(profile), set_active=False)
+        print(f"Logged out of OAuth for profile '{profile_name}'")
+    else:
+        print(f"Profile '{profile_name}' was not present")
+
+
+def _profile_without_oauth_session(profile: StoredProfile) -> StoredProfile:
+    return StoredProfile(
+        name=profile.name,
+        base_url=profile.base_url,
+        api_key=profile.api_key,
+        agent_id=profile.agent_id,
+        organization_id=profile.organization_id,
+        default_number_pool_id=profile.default_number_pool_id,
+        timeout_seconds=profile.timeout_seconds,
+    )
+
+
+def _try_revoke_oauth_session(base_url: str, refresh_handle: str, profile_name: str) -> None:
+    """Best-effort POST to /auth/cli/oauth/logout. Failures are non-fatal — local
+    profile cleanup proceeds regardless so a broken refresh handle can't trap the user."""
+    bootstrap_client = HttpClient(
+        base_url=base_url,
+        auth_selector=AuthSelector(api_key_auth=None, bearer_auth=None),
+        timeout_seconds=10,
+        agent_id=None,
+        organization_id=None,
+    )
+    cli_auth = CliAuthService(bootstrap_client)
+    try:
+        cli_auth.logout(refresh_handle)
+    except ApiError as exc:
+        print(
+            f"Warning: could not revoke server-side session for '{profile_name}' ({exc}).",
+            file=sys.stderr,
+        )
+        print(
+            "Local OAuth credentials will be cleared anyway. The session may remain active on the engine until it expires.",
+            file=sys.stderr,
+        )
+
+
+def handle_auth_status(args: argparse.Namespace) -> None:
+    store = ConfigStore()
+    profile_name = args.profile_name or args.profile or store.active_profile_name()
+    print(f"Config file: {store.path} ({'present' if store.exists() else 'missing'})")
+    profiles = store.list_profiles()
+    print(f"Profiles: {', '.join(profiles) if profiles else '(none)'}")
+    active = store.active_profile_name()
+    print(f"Active profile: {active or '(none)'}")
+    try:
+        resolved = EnvironmentConfig.resolve(profile_name)
+    except ConfigError as exc:
+        _print_error(str(exc))
+        sys.exit(1)
+    print("Resolved (env vars + CLI flags overlay the profile):")
+    print(f"  base_url:           {resolved.base_url}")
+    print(f"  api_key:            {mask_secret(resolved.api_key)}")
+    print(f"  bearer_token:       {mask_secret(resolved.bearer_token)}")
+    print(f"  refresh_handle:     {mask_secret(resolved.refresh_handle)}")
+    print(f"  access_token_exp:   {resolved.access_token_expires_at or '(unset)'}")
+    print(f"  cli_session_id:     {resolved.cli_session_id or '(unset)'}")
+    print(f"  agent_id:           {resolved.agent_id or '(unset)'}")
+    print(f"  org_id:             {resolved.organization_id or '(unset)'}")
+    print(f"  number_pool_id:     {resolved.default_number_pool_id or '(unset)'}")
+    print(f"  timeout:            {resolved.timeout_seconds}s")
+    print(f"  source:             {resolved.source_profile or '(env only)'}")
+    if resolved.bearer_token and resolved.refresh_handle and resolved.access_token_expires_at:
+        print("  auth mode:          OAuth (auto-refresh enabled)")
+    elif resolved.bearer_token:
+        print("  auth mode:          Static bearer (manual paste — no auto-refresh)")
+    elif resolved.api_key:
+        print("  auth mode:          API key only (credential-mgmt commands will fail)")
+    else:
+        print("  auth mode:          Not authenticated — run `guzli auth login --mode oauth`")
+
+
+def handle_auth_use(args: argparse.Namespace) -> None:
+    store = ConfigStore()
+    store.set_active(args.profile_name)
+    print(f"Active profile set to '{args.profile_name}'")
+
+
+def handle_auth_list(args: argparse.Namespace) -> None:
+    store = ConfigStore()
+    profiles = store.list_profiles()
+    if not profiles:
+        print("(no profiles configured)")
+        return
+    active = store.active_profile_name()
+    for name in profiles:
+        marker = "*" if name == active else " "
+        profile = store.get_profile(name)
+        base_url = profile.base_url if profile else ""
+        agent_id = profile.agent_id if profile else ""
+        print(f"{marker} {name:<20} {base_url}  agent={agent_id or '(unset)'}")
+
+
+def _add_auth_login(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser(
+        "login",
+        help="Log in via OAuth (recommended) or store a long-lived API key.",
+        description=(
+            "Two modes:\n"
+            "  --mode oauth (recommended): opens your browser, you log in once, CLI gets an\n"
+            "    engine-issued access token + opaque refresh handle. Auto-refreshes for 30 days.\n"
+            "    Required: --organization-id (which org to scope the session to).\n"
+            "  --mode api-key (legacy): prompts for a workspace API key. Use this only for\n"
+            "    non-credential commands (conversations, campaigns, calls, etc.) — credential-\n"
+            "    management routes (api-keys, webhooks, audit) require OAuth."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "--mode",
+        choices=["api-key", "oauth"],
+        default="api-key",
+        dest="login_mode",
+        help="Auth mode (default: api-key for backward compat)",
+    )
+    parser.add_argument("profile_name", nargs="?", help='Profile name (default: "default")')
+    parser.add_argument(
+        "--api-key",
+        dest="login_api_key",
+        help="[api-key mode] Skip the prompt; [oauth mode] preserve a fallback API key",
+    )
+    parser.add_argument("--agent-id", dest="login_agent_id", help="Skip the prompt")
+    parser.add_argument(
+        "--organization-id",
+        dest="login_organization_id",
+        help="Org scope (required for --mode oauth)",
+    )
+    parser.add_argument("--base-url", dest="login_base_url", help="Skip the prompt")
+    parser.add_argument(
+        "--callback-port",
+        dest="login_callback_port",
+        type=int,
+        help="[oauth mode] Localhost callback port registered with the engine (env: GUZLI_OAUTH_CALLBACK_PORT; default: 8765)",
+    )
+    parser.add_argument(
+        "--client-name",
+        dest="login_client_name",
+        default="Guzli CLI",
+        help="[oauth mode] Display name for this CLI session (shown in connected clients list)",
+    )
+    parser.add_argument(
+        "--no-activate",
+        action="store_true",
+        help="Save the profile but do not switch to it",
+    )
+    parser.set_defaults(handler=handle_auth_login, auth_only=True)
+
+
+def _add_auth_logout(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser(
+        "logout", help="Revoke OAuth credentials for a profile while preserving profile settings."
+    )
+    parser.add_argument("profile_name", nargs="?")
+    parser.add_argument("--all", action="store_true", help="Delete the entire config file")
+    parser.add_argument(
+        "--delete-profile",
+        action="store_true",
+        help="Delete the selected profile after revoking OAuth",
+    )
+    parser.set_defaults(handler=handle_auth_logout, auth_only=True)
+
+
+def _add_auth_status(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("status", help="Show resolved credentials (api key masked).")
+    parser.add_argument("profile_name", nargs="?", help="Inspect a specific profile")
+    parser.set_defaults(handler=handle_auth_status, auth_only=True)
+
+
+def _add_auth_use(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("use", help="Switch the active profile.")
+    parser.add_argument("profile_name")
+    parser.set_defaults(handler=handle_auth_use, auth_only=True)
+
+
+def _add_auth_list(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser("list", help="List stored profiles (active marked with *).")
+    parser.set_defaults(handler=handle_auth_list, auth_only=True)
+
+
+def _add_auth_list_clients(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser(
+        "list-clients",
+        help="List connected CLI sessions for your account (or the whole org if you are admin)",
+    )
+    parser.add_argument(
+        "--scope",
+        choices=["mine", "organization"],
+        default="mine",
+        help="'mine' = your sessions only (default). 'organization' = all org members' (admin only).",
+    )
+    _add_json_flag(parser)
+    parser.set_defaults(handler=handle_auth_list_clients)
+
+
+def _add_auth_revoke_client(sub: argparse._SubParsersAction) -> None:
+    parser = sub.add_parser(
+        "revoke-client",
+        help="Revoke a connected CLI session by id (kills it on every machine immediately)",
+    )
+    parser.add_argument("session_id", help="Session id from `auth list-clients`")
+    parser.add_argument("--confirm", action="store_true", help="Required to proceed")
+    parser.set_defaults(handler=handle_auth_revoke_client)
+
+
+def handle_auth_list_clients(context: RuntimeContext, args: argparse.Namespace) -> None:
+    payload = context.cli_auth.list_connected_clients(scope=args.scope)
+    if getattr(args, "json", False):
+        context.renderer.print_json(payload)
+        return
+    items = payload.get("items", []) if isinstance(payload, dict) else []
+    if not items:
+        print("No connected CLI sessions.")
+        return
+    for s in items:
+        revoked = " [REVOKED]" if s.get("revoked_at") else ""
+        last_used = s.get("last_used_at") or "never"
+        print(
+            f"{s.get('id')}  {s.get('client_display_name'):24}  "
+            f"user={s.get('user_email') or s.get('user_id')}  "
+            f"last_used={last_used}  expires={s.get('expires_at')}{revoked}"
+        )
+
+
+def handle_auth_revoke_client(context: RuntimeContext, args: argparse.Namespace) -> None:
+    if not args.confirm:
+        raise ValidationError("--confirm flag required to revoke a connected client")
+    context.cli_auth.revoke_connected_client(args.session_id)
+    print(f"Revoked CLI session {args.session_id}")
+
+
+def register(subparsers: argparse._SubParsersAction) -> None:
+    auth_parser = subparsers.add_parser("auth", help="Manage credentials & profiles")
+    auth_sub = auth_parser.add_subparsers(dest="auth_command", required=True)
+    _add_auth_login(auth_sub)
+    _add_auth_logout(auth_sub)
+    _add_auth_status(auth_sub)
+    _add_auth_use(auth_sub)
+    _add_auth_list(auth_sub)
+    _add_auth_list_clients(auth_sub)
+    _add_auth_revoke_client(auth_sub)

guzli/commands/campaign_launch.py

@@ -0,0 +1,188 @@
+from __future__ import annotations
+
+import argparse
+from collections.abc import Mapping
+
+from guzli.errors import ConfigError, ValidationError
+from guzli.runtime import RuntimeContext
+from guzli.validators import normalize_list, parse_json_or_file
+from guzli.workflows import CampaignLaunchInputs, CampaignLaunchWorkflow
+
+
+def handle_campaign_launch(context: RuntimeContext, args: argparse.Namespace) -> None:
+    agent_id = (args.agent_id or context.agent_id or "").strip()
+    organization_id = (
+        getattr(args, "organization_id", None) or context.organization_id or ""
+    ).strip()
+    if not organization_id:
+        raise ConfigError(
+            "organization_id is required. Set it via `guzli auth login --organization-id …`."
+        )
+    targets: list[str] = []
+    if args.target:
+        targets.extend(normalize_list(args.target))
+    if args.targets_file:
+        targets.extend(_read_targets_file(args.targets_file))
+    workflow = CampaignLaunchWorkflow(
+        telephony=context.telephony,
+        voice_profiles=context.voice_profiles,
+        campaigns=context.campaigns,
+    )
+    result = workflow.run(
+        CampaignLaunchInputs(
+            name=(args.name or "").strip(),
+            agent_id=agent_id,
+            organization_id=organization_id,
+            caller_phone_e164=(args.phone or "").strip() or None,
+            number_pool_id=(getattr(args, "number_pool_id", None) or "").strip() or None,
+            default_number_pool_id=context.default_number_pool_id,
+            voice_id=args.voice_id.strip() if args.voice_id else None,
+            voice_profile_id=args.voice_profile_id.strip() if args.voice_profile_id else None,
+            targets=targets,
+            telephony_account_id=(args.telephony_account_id or "").strip() or None,
+            call_instructions=(args.instructions or "").strip() or None,
+            runtime_objective=(args.objective or "").strip() or None,
+            initial_message=(args.message or "").strip() or None,
+            post_call_extraction=_resolve_extraction(args.extraction_json, args.extraction_file),
+            background_ambience=_resolve_background_ambience(
+                mode=args.background_ambience,
+                volume=args.ambience_volume,
+                transports=args.ambience_transports,
+            ),
+            voice_profile_name=(args.voice_profile_name or "").strip() or None,
+            configure_compliance=not args.skip_compliance,
+            compliance_mode=args.compliance_mode or "advisory",
+            disclosures_enabled=(bool(args.disclosures) if args.disclosures is not None else False),
+            activate=not args.no_activate,
+            run=not args.no_run,
+            dry_run=args.dry_run,
+        )
+    )
+    context.renderer.print_json(result.to_summary())
+
+
+def add_campaign_launch_parser(
+    sub: argparse._SubParsersAction,
+    *,
+    command_name: str = "launch",
+) -> None:
+    parser = sub.add_parser(
+        command_name,
+        help="Launch outbound calls using an existing number pool.",
+    )
+    parser.add_argument("--name", help="Campaign name; generated when omitted")
+    parser.add_argument(
+        "--number-pool-id",
+        dest="number_pool_id",
+        help="Existing pool; falls back to env, profile default, or only eligible pool",
+    )
+    parser.add_argument(
+        "--from",
+        "--phone",
+        dest="phone",
+        help="Match an existing pool containing this caller E.164",
+    )
+    parser.add_argument(
+        "--to",
+        "--target",
+        dest="target",
+        action="append",
+        help="Recipient E.164; repeatable or comma-separated",
+    )
+    parser.add_argument(
+        "--recipients-file",
+        "--targets-file",
+        dest="targets_file",
+        help="File with one recipient E.164 per line",
+    )
+    parser.add_argument("--voice-id", dest="voice_id")
+    parser.add_argument("--voice-profile-id", dest="voice_profile_id")
+    parser.add_argument("--message", help="Literal opening line")
+    parser.add_argument("--instructions", help="Call behavior and task instructions")
+    parser.add_argument("--objective", help="Optional compact runtime objective")
+    parser.add_argument("--extraction-file", dest="extraction_file")
+    parser.add_argument("--extraction-json", dest="extraction_json")
+    parser.add_argument("--telephony-account-id", dest="telephony_account_id")
+    parser.add_argument(
+        "--background-ambience",
+        dest="background_ambience",
+        choices=["none", "people_in_lounge", "food_court", "restaurant", "crowd_talking"],
+        default="people_in_lounge",
+    )
+    parser.add_argument("--ambience-volume", dest="ambience_volume", type=float, default=0.10)
+    parser.add_argument(
+        "--ambience-transport",
+        dest="ambience_transports",
+        action="append",
+        choices=["twilio", "webrtc"],
+    )
+    parser.add_argument("--voice-profile-name", dest="voice_profile_name")
+    parser.add_argument(
+        "--compliance-mode",
+        dest="compliance_mode",
+        choices=["advisory", "enforced"],
+    )
+    parser.add_argument(
+        "--disclosures",
+        dest="disclosures",
+        type=_parse_bool_flag,
+        metavar="on|off",
+        help="Spoken compliance disclosures; default off",
+    )
+    parser.add_argument("--skip-compliance", dest="skip_compliance", action="store_true")
+    parser.add_argument("--no-activate", action="store_true")
+    parser.add_argument("--no-run", action="store_true")
+    parser.add_argument("--dry-run", dest="dry_run", action="store_true")
+    parser.set_defaults(
+        handler=handle_campaign_launch,
+        launch_command_name=command_name,
+    )
+
+
+def _resolve_extraction(inline: str | None, file_path: str | None) -> dict[str, object] | None:
+    parsed = parse_json_or_file(inline, file_path, "post-call extraction")
+    if parsed is None:
+        return None
+    if isinstance(parsed, list):
+        return {"is_enabled": True, "fields": parsed}
+    if isinstance(parsed, Mapping):
+        settings = dict(parsed)
+        settings.setdefault("is_enabled", True)
+        return settings
+    raise ValidationError("post-call extraction must be a JSON object or a list")
+
+
+def _resolve_background_ambience(
+    *, mode: str, volume: float, transports: list[str] | None
+) -> dict[str, object] | None:
+    normalized_mode = (mode or "none").strip().lower()
+    if normalized_mode == "none":
+        return None
+    if not 0.0 <= volume <= 1.0:
+        raise ValidationError("--ambience-volume must be between 0.0 and 1.0")
+    payload: dict[str, object] = {"mode": normalized_mode, "volume": float(volume)}
+    if transports:
+        payload["transports"] = list(dict.fromkeys(item.strip().lower() for item in transports))
+    return payload
+
+
+def _read_targets_file(path: str) -> list[str]:
+    try:
+        with open(path.strip(), encoding="utf-8") as handle:
+            raw = handle.read()
+    except OSError as exc:
+        raise ValidationError(f"could not read recipients file {path}") from exc
+    return [
+        line.strip()
+        for line in raw.splitlines()
+        if line.strip() and not line.strip().startswith("#")
+    ]
+
+
+def _parse_bool_flag(value: str) -> bool:
+    normalized = value.strip().lower()
+    if normalized in {"true", "1", "yes", "on"}:
+        return True
+    if normalized in {"false", "0", "no", "off"}:
+        return False
+    raise argparse.ArgumentTypeError("expected on/off")