tiphys.events

  1"""
  2Typed event definitions for Tiphys.
  3
  4All events are Pydantic models for type safety and serialization.
  5"""
  6
  7from datetime import datetime
  8from typing import Literal
  9from uuid import uuid4
 10
 11from pydantic import BaseModel, Field
 12
 13
 14class BaseEvent(BaseModel):
 15    """Base class for all events."""
 16
 17    event_id: str = Field(default_factory=lambda: str(uuid4()))
 18    timestamp: datetime = Field(default_factory=datetime.utcnow)
 19
 20
 21# Agent Events
 22
 23
 24class ThoughtEvent(BaseEvent):
 25    """Agent's internal reasoning (may be hidden from user)."""
 26
 27    type: Literal["thought"] = "thought"
 28    content: str
 29    agent_id: str
 30
 31
 32class TextEvent(BaseEvent):
 33    """Text output from agent."""
 34
 35    type: Literal["text"] = "text"
 36    content: str
 37    agent_id: str
 38    is_final: bool = False
 39
 40
 41class ToolCallEvent(BaseEvent):
 42    """Agent is calling a tool."""
 43
 44    type: Literal["tool_call"] = "tool_call"
 45    tool_name: str
 46    arguments: dict[str, object]
 47    tool_call_id: str = Field(default_factory=lambda: str(uuid4()))
 48    agent_id: str
 49
 50
 51class ToolResultEvent(BaseEvent):
 52    """Result from a tool execution."""
 53
 54    type: Literal["tool_result"] = "tool_result"
 55    tool_call_id: str
 56    tool_name: str
 57    result: str
 58    success: bool
 59    agent_id: str
 60
 61
 62# Permission Events
 63
 64
 65class PermissionRequestEvent(BaseEvent):
 66    """Requesting user approval for an action."""
 67
 68    type: Literal["permission_request"] = "permission_request"
 69    request_id: str = Field(default_factory=lambda: str(uuid4()))
 70    action: str
 71    details: str
 72    agent_id: str
 73
 74
 75class PermissionResponseEvent(BaseEvent):
 76    """User's response to a permission request."""
 77
 78    type: Literal["permission_response"] = "permission_response"
 79    request_id: str
 80    approved: bool
 81    feedback: str | None = None
 82
 83
 84# Session Events
 85
 86
 87class SessionStartEvent(BaseEvent):
 88    """A session has started."""
 89
 90    type: Literal["session:start"] = "session:start"
 91    session_key: str
 92    agent_id: str
 93
 94
 95class SessionEndEvent(BaseEvent):
 96    """A session has ended."""
 97
 98    type: Literal["session:end"] = "session:end"
 99    session_key: str
100    duration_ms: int
101
102
103# System Events
104
105
106class ErrorEvent(BaseEvent):
107    """An error occurred."""
108
109    type: Literal["error"] = "error"
110    message: str
111    code: str | None = None
112    agent_id: str | None = None
113
114
115class StatusEvent(BaseEvent):
116    """System status update."""
117
118    type: Literal["status"] = "status"
119    status: Literal["ready", "busy", "error"]
120    message: str | None = None
121
122
123# Union of all event types
124EventType = (
125    ThoughtEvent
126    | TextEvent
127    | ToolCallEvent
128    | ToolResultEvent
129    | PermissionRequestEvent
130    | PermissionResponseEvent
131    | SessionStartEvent
132    | SessionEndEvent
133    | ErrorEvent
134    | StatusEvent
135)