{
  "$schema": "https://ag-ui.dev/schemas/protocol/v1",
  "protocolVersion": "1.0",
  "name": "Ghost AG-UI Protocol",
  "description": "Agent-User Interaction protocol for Ghost — defines how the Ghost agent streams real-time updates, tool calls, and state transitions to the frontend UI.",
  "transport": {
    "primary": "in_process",
    "fallback": ["websocket", "sse"],
    "description": "Ghost runs on-device so primary transport is in-process (Swift Observable / Kotlin StateFlow). WebSocket and SSE available for external agent integrations."
  },
  "events": {
    "lifecycle": [
      {
        "type": "agent.ready",
        "description": "Ghost models loaded and ready for inference",
        "payload": {
          "models_loaded": ["gate", "reflex", "workhorse"],
          "memory_items": "integer",
          "language": "string"
        }
      },
      {
        "type": "agent.degraded",
        "description": "Ghost has reduced capability due to thermal/battery/memory pressure",
        "payload": {
          "state": "full_power|balanced|conservative|minimal|emergency",
          "reason": "thermal|battery|ram|model_unloaded"
        }
      }
    ],
    "conversation": [
      {
        "type": "turn.start",
        "description": "User initiated a new conversation turn",
        "payload": {
          "source": "typed|voice",
          "language_detected": "string",
          "turn_id": "string"
        }
      },
      {
        "type": "turn.routing",
        "description": "Ghost is routing the request to the appropriate model tier",
        "payload": {
          "complexity_score": "float",
          "tier_target": "gate|reflex|workhorse",
          "workhorse_required": "boolean"
        }
      },
      {
        "type": "turn.thinking",
        "description": "Model is processing (in think block or pre-first-token)",
        "payload": {
          "tier": "string",
          "is_thinking": "boolean"
        }
      },
      {
        "type": "turn.token",
        "description": "Streaming token from the model",
        "payload": {
          "token": "string",
          "cumulative_length": "integer"
        }
      },
      {
        "type": "turn.complete",
        "description": "Model finished generating response",
        "payload": {
          "tier_used": "string",
          "total_tokens": "integer",
          "ttft_ms": "integer",
          "tps": "float",
          "quality_pass": "boolean",
          "language": "string"
        }
      },
      {
        "type": "turn.upgrade",
        "description": "Reflex response is being upgraded with Workhorse model",
        "payload": {
          "reason": "complexity|hedging|user_requested_detail"
        }
      },
      {
        "type": "turn.error",
        "description": "Generation failed",
        "payload": {
          "error": "string",
          "recoverable": "boolean"
        }
      }
    ],
    "voice": [
      {
        "type": "voice.listening",
        "description": "Microphone activated, waiting for speech"
      },
      {
        "type": "voice.speech_start",
        "description": "Voice activity detected"
      },
      {
        "type": "voice.transcribing",
        "description": "Whisper STT processing audio",
        "payload": {
          "language_detected": "string"
        }
      },
      {
        "type": "voice.transcript",
        "description": "Final transcript from STT",
        "payload": {
          "text": "string",
          "confidence": "float",
          "language": "string",
          "stt_ms": "integer"
        }
      },
      {
        "type": "voice.speaking",
        "description": "TTS is speaking the response",
        "payload": {
          "word": "string",
          "language": "string"
        }
      },
      {
        "type": "voice.barge_in",
        "description": "User interrupted AI speech"
      },
      {
        "type": "voice.finished",
        "description": "TTS finished speaking"
      }
    ],
    "memory": [
      {
        "type": "memory.recalled",
        "description": "Ghost retrieved relevant memories for context",
        "payload": {
          "count": "integer",
          "retrieve_ms": "integer"
        }
      },
      {
        "type": "memory.stored",
        "description": "New memory extracted and stored from conversation",
        "payload": {
          "type": "fact|preference|event|entity",
          "importance": "float"
        }
      }
    ],
    "tool_calls": [
      {
        "type": "tool.invoked",
        "description": "Ghost invoked an internal tool or capability",
        "payload": {
          "tool_name": "string",
          "arguments": "object"
        }
      },
      {
        "type": "tool.result",
        "description": "Tool call completed with result",
        "payload": {
          "tool_name": "string",
          "result": "object",
          "duration_ms": "integer"
        }
      }
    ]
  },
  "stateModel": {
    "states": ["idle", "listening", "transcribing", "thinking", "speaking", "error"],
    "transitions": [
      {"from": "idle", "to": "listening", "trigger": "user_activates_mic"},
      {"from": "idle", "to": "thinking", "trigger": "user_sends_text"},
      {"from": "listening", "to": "transcribing", "trigger": "speech_end"},
      {"from": "transcribing", "to": "thinking", "trigger": "stt_complete"},
      {"from": "thinking", "to": "speaking", "trigger": "first_token"},
      {"from": "speaking", "to": "idle", "trigger": "tts_complete"},
      {"from": "speaking", "to": "listening", "trigger": "auto_resume"},
      {"from": "speaking", "to": "listening", "trigger": "barge_in"},
      {"from": "any", "to": "idle", "trigger": "cancel"},
      {"from": "any", "to": "error", "trigger": "error"}
    ]
  }
}