Fix error handling and edge cases across auth, keys, and agent systems (#207)

This PR hardens error handling and fixes edge cases across multiple
subsystems to prevent crashes and improve user experience.

## Summary
Fixes malformed API responses, corrupt configuration handling, invalid
base64 audio frames, and platform-specific upgrade detection. Also
improves sentence splitting logic to preserve decimals and
abbreviations, and corrects environment variable resolution for Voice
Agents.

## Key Changes

**Auth & Keys**
- Split `find_or_create_cli_key` tests into a dedicated module to keep
`test_auth_flow.py` under the 500-line gate
- Add validation in `keys create` to reject API responses missing or
with empty `api_key` field, surfacing clean `APIError` instead of
`KeyError`
- Improve `find_or_create_cli_key` to use the first project entry that
actually has a project object (not just the first entry), handling
accounts where the first membership lacks a project

**Configuration & Startup**
- Guard the onboarding wizard offer against corrupt `config.toml` by
checking `deferred_config_error` before attempting to resolve
credentials, preventing traceback when config is unparseable
- Add test coverage for bare `assembly` command with corrupt config

**Agent Session**
- Wrap base64 decoding in `on_reply_audio` with try-except to gracefully
drop corrupt audio frames instead of crashing the live conversation
session

**Text Processing**
- Refine `split_sentences` to only treat terminators (`.`, `!`, `?`) as
sentence boundaries when they end the text or are followed by
whitespace, preserving decimals ("$3.50") and abbreviations, and keeping
stacked terminators ("...", "?!") intact

**Environment & Deployment**
- Fix `_active_env_vars` to use the authoritative `agents_host` field
from the environment instead of deriving it via string replacement of
`streaming_host`
- Fix `dev_command` to swap both `python` and `python3` leading tokens
for the venv interpreter
- Fix `detect_upgrade_command` to only treat `/usr/local/bin` as
Homebrew on macOS (darwin), not on Linux where it's a conventional
source/manual build prefix
- Add platform-specific test coverage for upgrade detection

**Code Generation**
- Add null-check for LLM gateway message content to prevent crashes
during code generation

## Testing
- Added 9 new tests covering malformed responses, corrupt config,
corrupt audio frames, sentence splitting edge cases, and
platform-specific upgrade detection
- Moved 7 existing `find_or_create_cli_key` tests to new
`test_auth_flow_projects.py` module

https://claude.ai/code/session_0119PsP7ZmuXMsoMke7DBBd2

Co-authored-by: Claude <noreply@anthropic.com>

Author: alexkroman

aai_cli/agent/session.py

@@ -132,8 +132,13 @@ def on_reply_started(self, _event: dict[str, Any]) -> None:
 
     def on_reply_audio(self, event: dict[str, Any]) -> None:
         data = event.get("data")
-        if data:
-            self.player.enqueue(base64.b64decode(data))
+        if not data:
+            return
+        try:
+            pcm = base64.b64decode(data)
+        except (ValueError, TypeError):
+            return  # a single corrupt frame is dropped, not fatal to the session
+        self.player.enqueue(pcm)
 
     def on_agent_transcript(self, event: dict[str, Any]) -> None:
         self.renderer.agent_transcript(

aai_cli/agent_cascade/text.py

@@ -14,15 +14,19 @@
 def split_sentences(text: str) -> list[str]:
     """Split ``text`` into sentences, each ending in ``.``/``!``/``?``.
 
-    A trailing fragment with no terminal punctuation is kept as a final sentence,
-    so no text is ever dropped; empty/whitespace-only pieces are discarded.
+    A terminator ends a sentence only when it is the last character or is followed by
+    whitespace — so a ``.`` inside a number ("$3.50") or stacked terminators ("..."/"?!")
+    don't fragment one spoken sentence into several TTS calls (which both clips audio
+    mid-number and writes a space-mangled copy back into the LLM history). A trailing
+    fragment with no terminal punctuation is kept, so no text is ever dropped;
+    empty/whitespace-only pieces are discarded.
     """
     sentences: list[str] = []
     start = 0
     for index, char in enumerate(text):
-        if char in _TERMINATORS:
-            # The slice always includes the terminator at ``index``, so it is never
-            # blank after stripping the inter-sentence whitespace.
+        if char in _TERMINATORS and (index + 1 == len(text) or text[index + 1].isspace()):
+            # Boundary confirmed (end-of-text or a following space); the slice includes
+            # the terminator, so it is never blank after stripping leading whitespace.
             sentences.append(text[start : index + 1].strip())
             start = index + 1
     tail = text[start:].strip()

aai_cli/app/init_exec.py

@@ -103,8 +103,9 @@ def _active_env_vars() -> dict[str, str]:
         "ASSEMBLYAI_BASE_URL": env.api_base,
         "ASSEMBLYAI_LLM_GATEWAY_URL": env.llm_gateway_base,
         "ASSEMBLYAI_STREAMING_HOST": env.streaming_host,
-        # Voice Agent host mirrors the streaming host's naming across environments.
-        "ASSEMBLYAI_AGENTS_HOST": env.streaming_host.replace("streaming", "agents", 1),
+        # The environment's authoritative Voice Agent host (not derived from the
+        # streaming host, which only coincides by naming convention today).
+        "ASSEMBLYAI_AGENTS_HOST": env.agents_host,
         # Streaming-TTS host for the cascade (agent-cascade) template. Empty in
         # production, where streaming TTS has no host; that template then refuses to
         # run and points at --sandbox.

aai_cli/auth/flow.py

@@ -167,15 +167,17 @@ def _no_project_error() -> APIError:
 
 
 def find_or_create_cli_key(account_id: int, session_jwt: str) -> str:
-    """Return the existing 'AssemblyAI CLI' key, or create one in the first project."""
+    """Return the existing 'AssemblyAI CLI' key, or create one in the first usable project."""
     projects = _parse(_PROJECT_LIST, ams.list_projects(account_id, session_jwt))
     if not projects:
         raise _no_project_error()
     for entry in projects:
         for token in entry.tokens:
             if key := _reusable_cli_key(token):
                 return key
-    project = projects[0].project
+    # Mint into the first entry that actually carries a project — an account whose
+    # first membership has no project can still have a usable one later in the list.
+    project = next((entry.project for entry in projects if entry.project is not None), None)
     if project is None:
         raise _no_project_error()
     created = ams.create_token(account_id, project.id, endpoints.CLI_TOKEN_NAME, session_jwt)

aai_cli/code_gen/stream.py

@@ -74,7 +74,7 @@ def run_chain(text: str) -> str:
             messages=[{{"role": "user", "content": prompt + "\\n\\nTranscript:\\n" + source}}],
             max_tokens={max_tokens},
         )
-        result = response.choices[0].message.content
+        result = response.choices[0].message.content or ""
     return result
 
 

aai_cli/commands/keys.py

@@ -139,11 +139,19 @@ def body(state: AppState, json_mode: bool) -> None:
         account_id, jwt = state.resolve_session()
         pid = project_id if project_id is not None else _default_project_id(account_id, jwt)
         created = ams.create_token(account_id, pid, name, jwt)
+        # Validate before rendering: a 200 whose body omits api_key (proxy/version
+        # drift) must surface a clean APIError, not a KeyError traceback.
+        api_key = created.get("api_key")
+        if not isinstance(api_key, str) or not api_key:
+            raise APIError(
+                "AMS created the key but returned no api_key.",
+                suggestion="Run 'assembly keys list' to confirm it exists, then try again.",
+            )
         output.emit(
             created,
-            lambda d: (
+            lambda _d: (
                 output.success(f"Created API key '{escape(name)}'.")
-                + f"\n  {escape(str(d['api_key']))}\n"
+                + f"\n  {escape(api_key)}\n"
                 + output.warn("Shown once — copy it now.")
             ),
             json_mode=json_mode,

aai_cli/init/devserver.py

@@ -56,14 +56,14 @@ def dev_command(target: Path, web: list[str], *, use_uv: bool, host: str = LOCAL
     """The Procfile web process, run in the project venv with live reload.
 
     The Procfile's `web:` line starts with `python -m uvicorn …`. With uv, run it
-    under `uv run`; without uv, swap a leading `python` for the project's venv
-    interpreter so it runs inside the scaffolded `.venv`. In both cases the
+    under `uv run`; without uv, swap a leading `python`/`python3` for the project's
+    venv interpreter so it runs inside the scaffolded `.venv`. In both cases the
     Procfile's `--host 0.0.0.0` is overridden to `host` (loopback by default) so a
     local dev run never exposes the server — and the key in `.env` — to the LAN.
     """
     argv = _override_host(web, host)
     if use_uv:
         return ["uv", "run", *argv, "--reload"]
-    if argv and argv[0] == "python":
+    if argv and argv[0] in ("python", "python3"):
         argv[0] = str(runner.venv_python(target))
     return [*argv, "--reload"]

aai_cli/main.py

@@ -110,11 +110,18 @@ def _sandbox_conflict_warning(sandbox: bool, env: str | None) -> str | None:
 
 def _offer_or_help(ctx: typer.Context, state: AppState) -> None:
     """No subcommand given: offer guided setup to a credential-less, interactive user;
-    otherwise print help. Never prompts in a non-interactive session, and never on
-    `--help` (Click handles that eagerly before the callback)."""
+    otherwise print help. Never prompts in a non-interactive session, never on
+    `--help` (Click handles that eagerly before the callback), and never when the
+    stored config is unparseable — a deferred ``invalid_config`` error means
+    ``resolve_api_key``/``resolve_profile`` would re-raise (escaping the callback as
+    a traceback), and the wizard would only write atop a broken file."""
     if not state.quiet:
         output.print_banner()
-    if stdio.interactive_stdio() and not _profile_has_key(state):
+    if (
+        state.deferred_config_error is None
+        and stdio.interactive_stdio()
+        and not _profile_has_key(state)
+    ):
         if not state.quiet:
             output.console.print()  # blank line so the prompt isn't flush against the banner
         if typer.confirm("Welcome to AssemblyAI. Run guided setup now?", default=True):

aai_cli/ui/update_check.py

@@ -44,7 +44,9 @@ def is_newer(latest: str, current: str) -> bool:
 
 
 def _is_homebrew_executable(executable: str) -> bool:
-    if executable.startswith("/usr/local/"):
+    # /usr/local/ is Homebrew only on Intel macOS; on Linux it's the conventional
+    # prefix for source/manually-built interpreters, so don't claim brew there.
+    if sys.platform == "darwin" and executable.startswith("/usr/local/"):
         return True
     return any(marker in executable for marker in _HOMEBREW_PATH_MARKERS)
 
@@ -84,7 +86,7 @@ def fetch_and_cache() -> None:
         resp.raise_for_status()
         tag = resp.json().get("tag_name")
         if isinstance(tag, str) and tag:
-            latest = tag.lstrip("v")
+            latest = tag.removeprefix("v")
     except (httpx.HTTPError, ValueError, KeyError, OSError):
         latest = None
     try:

tests/test_agent_cascade_text.py

@@ -21,10 +21,24 @@ def test_split_sentences_empty_string_is_empty_list():
     assert split_sentences("") == []
 
 
-def test_split_sentences_each_terminator_ends_a_sentence():
-    # Every terminator closes the current chunk, so consecutive ones each yield one.
-    assert split_sentences("...") == [".", ".", "."]
+def test_split_sentences_terminator_followed_by_space_ends_a_sentence():
+    # A terminator only closes the chunk when it ends the text or is followed by space.
     assert split_sentences(" . ") == ["."]
+    assert split_sentences("Hi . Bye .") == ["Hi .", "Bye ."]
+
+
+def test_split_sentences_keeps_decimals_and_abbreviations_intact():
+    # A '.' wedged between non-space characters is not a sentence boundary, so a
+    # number ("$3.50") or abbreviation stays one piece instead of fragmenting TTS.
+    assert split_sentences("It costs $3.50 today.") == ["It costs $3.50 today."]
+    assert split_sentences("Total 12.5") == ["Total 12.5"]
+
+
+def test_split_sentences_does_not_split_stacked_terminators():
+    # Ellipsis and "?!" are followed by non-space chars (or each other), so they
+    # don't each spawn a separate sentence.
+    assert split_sentences("...") == ["..."]
+    assert split_sentences("Wait...what?!") == ["Wait...what?!"]
 
 
 def test_trim_history_drops_oldest_beyond_limit():