Agent Creation

Implement TIE agent creation following these rules:

TIE is the cross-app source of truth for every user's AI agent. Each user has exactly
one non-preset persona on TIE, shared across all apps (BlinkLife, Vibrantly, etc).

BASE URL: https://your-tie-host
AUTH: All persona and voice endpoints use a Bearer token issued by TIE Auth for the
      end user. Do NOT use a service key here — these are user-scoped endpoints.

---

STEP 1 — CHECK FOR EXISTING AGENT

  GET /personas
  Authorization: Bearer $USER_TOKEN

  Response: array of persona objects. Each object has:
    id: string (UUID)
    name: string
    system_prompt: string
    archetype: string | null
    description: string | null
    is_preset: boolean        ← presets are platform defaults; false = user's own agent
    is_active: boolean        ← true if currently active for this user
    created_at: ISO datetime
    updated_at: ISO datetime

  Filter for is_preset: false. If one exists → GO TO "SKIP SETUP" below.
  If none exists → GO TO STEP 2.

---

SKIP SETUP (persona already exists):
  - Do NOT create another persona. Each user has exactly one non-preset persona.
  - Do NOT prompt the user to choose a name, archetype, or voice.
  - Voice is already stored on TIE (or falls back to gemini/Kore if never set).
  - Mark this app's onboarding as complete in your own DB.
  - Route the user directly into the app.

---

STEP 2 — CREATE THE PERSONA

  POST /personas
  Authorization: Bearer $USER_TOKEN
  Content-Type: application/json

  {
    "name": "Aria",
    "system_prompt": "You are Aria, a SAGE companion...",
    "archetype": "SAGE",
    "description": null          // optional
  }

  Field rules:
    name: required, 1–255 chars
    system_prompt: required, min 1 char
    archetype: optional, max 100 chars. Recommended values: SAGE, FRIEND, COACH, REBEL, NURTURER
    description: optional

  On success: 201 with the created persona object (same shape as GET /personas items).
  Save the returned id — you need it for steps 3 and 4.

  Errors:
    422 VALIDATION_ERROR — invalid field values
    503 PERSONA_SYSTEM_UNAVAILABLE — TIE persona store is down; surface an error to the user

---

STEP 3 — SET PERSONA AS ACTIVE

  PUT /personas/active/{persona_id}
  Authorization: Bearer $USER_TOKEN

  Response: { "status": "active", "persona_id": "..." }

  Errors:
    404 PERSONA_NOT_FOUND — persona_id doesn't exist or isn't owned by this user

---

STEP 4 — SAVE VOICE PREFERENCE

  PUT /v1/voice/preferences/{persona_id}
  Authorization: Bearer $USER_TOKEN
  Content-Type: application/json

  {
    "provider": "gemini",
    "voice": "Kore",
    "language": "en"
  }

  Field rules:
    provider: string, default "gemini"
    voice: required, one of: Kore, Puck, Charon, Aoede, Fenrir, Leda, Orus, Zephyr
    language: required, BCP-47 code (e.g. "en")

  Response: { "provider": "gemini", "voice": "Kore", "language": "en" }

  If you skip this call, the persona falls back to gemini/Kore.

  Errors:
    404 PERSONA_NOT_FOUND — persona doesn't exist or not owned by user
    503 SERVICE_UNAVAILABLE — voice store is down

---

VOICE PREVIEW (during voice selection UI):

  POST /v1/audio/speech
  Authorization: Bearer $USER_TOKEN
  Content-Type: application/json

  {
    "model": "google/gemini-2.5-flash-tts",
    "input": "Hi, I'm Aria. Nice to meet you.",
    "voice": "Kore"
  }

  Returns PCM/WAV audio bytes. Play directly in browser or mobile.

---

GET SAVED VOICE (to display current selection):

  GET /v1/voice/preferences/{persona_id}
  Authorization: Bearer $USER_TOKEN

  Returns: { "provider": "gemini", "voice": "Kore", "language": "en" }
  Falls back to gemini/Kore/en defaults if never saved.

---

COMPLETE FLOW SUMMARY:

  1. GET /personas → find is_preset: false
  2a. Found   → skip setup, mark app onboarding done, enter app
  2b. Missing → POST /personas (save returned id)
               → PUT /personas/active/{id}
               → PUT /v1/voice/preferences/{id}
               → mark app onboarding done, enter app

1. GET /personas → find existing non-preset persona
2a. Found     → skip setup entirely, mark onboarding complete (voice already on TIE)
2b. Not found → run setup:
                  POST /personas to create
                  PUT  /personas/active/{id}
                  PUT  /v1/voice/preferences/{id}  (selected Gemini voice for that persona)

GET https://your-tie-host/personas
Authorization: Bearer $USER_TOKEN

POST https://your-tie-host/personas
Authorization: Bearer $USER_TOKEN
Content-Type: application/json

{
  "name": "Aria",
  "system_prompt": "You are Aria, a SAGE companion...",
  "archetype": "SAGE"
}

PUT https://your-tie-host/personas/active/{persona_id}
Authorization: Bearer $USER_TOKEN

PUT https://your-tie-host/v1/voice/preferences/{persona_id}
Authorization: Bearer $USER_TOKEN
Content-Type: application/json

{
  "provider": "gemini",
  "voice": "Kore",
  "language": "en"
}