protocol

type ActionEnvelope struct {
	// The action to perform.
	Action ActionEnvelopeAction `json:"action"`

	// Client-generated correlation ID. Will be echoed back on all related server
	// events. Should be unique per in-flight request. If omitted the server may
	// generate one, but correlating responses becomes the client's problem.
	RequestID *string `json:"requestId,omitempty,omitzero"`

	AdditionalProperties interface{} `mapstructure:",remain"`
}

type ActionEnvelopeAction string

type ActionType string

type Checkpoint struct {
	// The agent whose state is captured in this checkpoint.
	AgentID string `json:"agentId"`

	// ISO 8601 timestamp when the checkpoint was created.
	CreatedAt time.Time `json:"createdAt"`

	// Unique checkpoint identifier (UUID v4).
	ID string `json:"id"`

	// Agent loop iteration counter at the time the checkpoint was taken.
	Iteration int `json:"iteration"`

	// Arbitrary string key/value metadata attached to this checkpoint (e.g. phase
	// name, bead ID).
	Metadata CheckpointMetadata `json:"metadata,omitempty,omitzero"`

	// smooth-operator workflow thread identifier this checkpoint belongs to. Matches
	// `Session.threadId` for the associated session.
	ThreadID string `json:"threadId"`
}

type CheckpointMetadata map[string]string

type Citation struct {
	// Stable identifier of the cited source document (the knowledge-base
	// `document_id`). Used to deduplicate citations within a turn.
	ID string `json:"id"`

	// Relevance score of this source for the turn's query (the knowledge-base
	// similarity score). Higher is more relevant.
	Score float64 `json:"score"`

	// The retrieved chunk text that grounded the answer, truncated to a bounded
	// length for display.
	Snippet string `json:"snippet"`

	// Human-readable label for the source — typically the document's source path or,
	// for web-sourced docs, the URL/title.
	Title string `json:"title"`

	// Canonical link to the source, when one exists. For GitHub-sourced documents
	// this is the blob/issue URL stamped onto the document's `source` at ingest (see
	// CONNECTORS.md). Absent for sources with no web location (e.g. uploaded files).
	URL *string `json:"url,omitempty,omitzero"`
}

type Client struct {
	// contains filtered or unexported fields
}

type ConfirmToolActionParams struct {
	SessionID string `json:"sessionId"`
	// RequestID must match the write_confirmation_required event being answered.
	RequestID string `json:"requestId"`
	Approved  bool   `json:"approved"`
}

type ConfirmToolActionRequest struct {
	// Action discriminator.
	Action string `json:"action"`

	// True to allow the tool call to proceed; false to reject it. On rejection the
	// agent workflow resumes with an informational context message.
	Approved bool `json:"approved"`

	// Must match the `requestId` from the `write_confirmation_required` event being
	// responded to. This is how the server correlates the confirmation back to the
	// paused workflow.
	RequestID string `json:"requestId"`

	// Session ID of the paused session.
	SessionID string `json:"sessionId"`
}

type ConfirmToolActionResponse map[string]interface{}

type ContentItem struct {
	// The text content (required when type = `text`).
	Text *string `json:"text,omitempty,omitzero"`

	// Content item type discriminator.
	Type ContentItemType `json:"type"`
}

type ContentItemType string

type Conversation struct {
	// Analytics and scoring data aggregated from messages in this conversation.
	AnalyticsJSON ConversationAnalyticsJSON `json:"analyticsJson,omitempty,omitzero"`

	// ISO 8601 timestamp when the conversation was created.
	CreatedAt time.Time `json:"createdAt"`

	// Unique conversation identifier.
	ID string `json:"id"`

	// Client-provided key that prevents duplicate conversations from being created
	// for the same logical thread.
	IdempotencyKey string `json:"idempotencyKey"`

	// Arbitrary key/value metadata attached to the conversation (e.g. campaign
	// source, CRM fields).
	MetadataJSON ConversationMetadataJSON `json:"metadataJson,omitempty,omitzero"`

	// Human-readable display name for the conversation.
	Name string `json:"name"`

	// The organization that owns this conversation.
	OrganizationID string `json:"organizationId"`

	// The channel on which this conversation takes place.
	Platform ConversationPlatform `json:"platform"`

	// ISO 8601 timestamp when the conversation was last updated.
	UpdatedAt time.Time `json:"updatedAt"`
}

type ConversationAnalyticsJSON map[string]interface{}

type ConversationMessage struct {
	// Message payload. `text` contains the plain-text form; `structuredResponse`
	// contains parsed agent output when present.
	Content ConversationMessageContent `json:"content"`

	// ISO 8601 timestamp when the message was created.
	CreatedAt time.Time `json:"createdAt"`

	// Message direction: `inbound` = from user, `outbound` = from agent.
	Direction ConversationMessageDirection `json:"direction"`

	// Abbreviated sender descriptor.
	From *ConversationMessageFrom `json:"from,omitempty,omitzero"`

	// Unique message ID.
	ID string `json:"id"`

	// Abbreviated recipient descriptor.
	To *ConversationMessageTo `json:"to,omitempty,omitzero"`
}

type ConversationMessageContent struct {
	// Structured agent response (shape depends on agent template).
	StructuredResponse *ConversationMessageContentStructuredResponse `json:"structuredResponse,omitempty,omitzero"`

	// Plain-text content.
	Text *string `json:"text,omitempty,omitzero"`
}

type ConversationMessageContentStructuredResponse map[string]interface{}

type ConversationMessageDirection string

type ConversationMessageFrom struct {
	// ID corresponds to the JSON schema field "id".
	ID string `json:"id"`

	// Name corresponds to the JSON schema field "name".
	Name *string `json:"name,omitempty,omitzero"`

	// Type corresponds to the JSON schema field "type".
	Type string `json:"type"`
}

type ConversationMessageTo struct {
	// ID corresponds to the JSON schema field "id".
	ID string `json:"id"`

	// Name corresponds to the JSON schema field "name".
	Name *string `json:"name,omitempty,omitzero"`

	// Type corresponds to the JSON schema field "type".
	Type string `json:"type"`
}

type ConversationMetadataJSON map[string]interface{}

type ConversationPlatform string

type CreateConversationSessionParams struct {
	AgentID            string                 `json:"agentId"`
	UserName           string                 `json:"userName,omitempty"`
	UserEmail          string                 `json:"userEmail,omitempty"`
	BrowserFingerprint string                 `json:"browserFingerprint,omitempty"`
	Metadata           map[string]interface{} `json:"metadata,omitempty"`
	AuthContext        *RequestAuthContext    `json:"authContext,omitempty"`
}

type CreateConversationSessionRequest struct {
	// Action discriminator.
	Action string `json:"action"`

	// UUID of the agent to start a session with.
	AgentID string `json:"agentId"`

	// Pre-auth context for HMAC-based identity verification. When provided, the
	// server can skip OTP flows by verifying the HMAC signature instead.
	AuthContext *RequestAuthContext `json:"authContext,omitempty,omitzero"`

	// Browser fingerprint string (e.g. from ThumbmarkJS) used for anonymous user
	// correlation across sessions.
	BrowserFingerprint *string `json:"browserFingerprint,omitempty,omitzero"`

	// Arbitrary key/value metadata to attach to the session.
	Metadata RequestMetadata `json:"metadata,omitempty,omitzero"`

	// Client-generated correlation ID echoed back on all related events.
	RequestID *string `json:"requestId,omitempty,omitzero"`

	// Optional email address for the user participant.
	UserEmail *string `json:"userEmail,omitempty,omitzero"`

	// Optional display name for the user participant.
	UserName *string `json:"userName,omitempty,omitzero"`
}

type CreateConversationSessionResponse struct {
	// ID of the agent handling this session.
	AgentID string `json:"agentId"`

	// Display name of the agent.
	AgentName string `json:"agentName"`

	// Participant ID representing the AI agent in this conversation.
	AgentParticipantID string `json:"agentParticipantId"`

	// ID of the conversation created for this session.
	ConversationID string `json:"conversationId"`

	// Newly created session ID. Use this in all subsequent actions.
	SessionID string `json:"sessionId"`

	// Participant ID representing the user in this conversation.
	UserParticipantID string `json:"userParticipantId"`
}

type Error struct {
	// Full error payload.
	Data ErrorData `json:"data"`

	// Top-level error object (duplicate of `data.error`; kept for clients that
	// pattern-match on the envelope-level `error` field).
	Error *ErrorError `json:"error,omitempty,omitzero"`

	// Echoes the `requestId` from the originating action, if applicable. Absent for
	// server-initiated errors with no associated request.
	RequestID *string `json:"requestId,omitempty,omitzero"`

	// Unix epoch milliseconds when the event was emitted.
	Timestamp *int `json:"timestamp,omitempty,omitzero"`

	// Event type discriminator.
	Type string `json:"type"`
}

type ErrorData struct {
	// Optional additional structured error context (e.g. validation issues, partial
	// results).
	Details interface{} `json:"details,omitempty,omitzero"`

	// The error descriptor (nested for wire backward-compatibility).
	Error ErrorDataError `json:"error"`

	// The request ID this error belongs to, if any.
	RequestID *string `json:"requestId,omitempty,omitzero"`
}

type ErrorDataError struct {
	// Machine-readable error code (e.g. `SESSION_NOT_FOUND`, `RATE_LIMITED`,
	// `VALIDATION_ERROR`, `INTERNAL_ERROR`).
	Code string `json:"code"`

	// Human-readable error description.
	Message string `json:"message"`
}

type ErrorError struct {
	// Machine-readable error code.
	Code string `json:"code"`

	// Human-readable error description.
	Message string `json:"message"`
}

type ErrorObject struct {
	// Machine-readable error code (e.g. `SESSION_NOT_FOUND`, `RATE_LIMITED`,
	// `VALIDATION_ERROR`).
	Code string `json:"code"`

	// Human-readable error description.
	Message string `json:"message"`
}

type EventEnvelope struct {
	// Event-specific payload. Shape is defined by the per-event schema in `events/`.
	Data interface{} `json:"data,omitempty,omitzero"`

	// Present on `error` events.
	Error *ErrorObject `json:"error,omitempty,omitzero"`

	// Optional human-readable status description (used in `immediate_response` acks).
	Message *string `json:"message,omitempty,omitzero"`

	// Name of the workflow node that produced this event. Present on `stream_chunk`
	// events.
	Node *string `json:"node,omitempty,omitzero"`

	// Echoes the `requestId` from the originating action. Absent for unsolicited
	// server-push events.
	RequestID *string `json:"requestId,omitempty,omitzero"`

	// HTTP-like status code. 202 = acknowledged/in-progress; 200 = final success;
	// 4xx/5xx = error conditions.
	Status *int `json:"status,omitempty,omitzero"`

	// Unix epoch milliseconds. Present on `pong` events and optionally on others.
	Timestamp *int `json:"timestamp,omitempty,omitzero"`

	// A streamed LLM token. Present on `stream_token` events.
	Token *string `json:"token,omitempty,omitzero"`

	// Identifies which event this frame carries.
	Type EventEnvelopeType `json:"type"`
}

type EventEnvelopeType string

type EventType string

type EventualResponse struct {
	// The terminal response payload.
	Data EventualResponseData `json:"data"`

	// Echoes the `requestId` from the originating `send_message` action.
	RequestID *string `json:"requestId,omitempty,omitzero"`

	// HTTP-like status. Always 200 for a successful eventual response.
	Status *int `json:"status,omitempty,omitzero"`

	// Unix epoch milliseconds when the event was emitted.
	Timestamp *int `json:"timestamp,omitempty,omitzero"`

	// Event type discriminator.
	Type string `json:"type"`
}

type EventualResponseData struct {
	// The final agent output.
	Data EventualResponseDataData `json:"data"`

	// The request ID this response belongs to.
	RequestID string `json:"requestId"`

	// HTTP-like status. Typically 200.
	Status int `json:"status"`
}

type EventualResponseDataData struct {
	// The sources that grounded this answer, when any were retrieved. Collected by
	// the runtime from the documents that actually grounded the turn — the
	// auto-injected `[Relevant knowledge]` context and any `knowledge_search` tool
	// results — deduplicated by source id and capped. Optional and back-compatible:
	// absent when the turn used no knowledge sources. Each item is a `Citation` (see
	// `domain/citation.schema.json`).
	Citations []EventualResponseDataDataCitationsElem `json:"citations,omitempty,omitzero"`

	// Human-readable escalation reason when `needsEscalation` is true.
	EscalationReason *string `json:"escalationReason,omitempty,omitzero"`

	// ID of the agent message as persisted to the `conversation_messages` table.
	MessageID string `json:"messageId"`

	// True if the agent flagged this conversation for human escalation.
	NeedsEscalation *bool `json:"needsEscalation,omitempty,omitzero"`

	// The structured agent response payload. Shape depends on the agent template.
	// Clients should validate against a template-specific schema before rendering.
	Response interface{} `json:"response"`
}

type EventualResponseDataDataCitationsElem struct {
	// Stable identifier of the cited source document (the knowledge-base
	// `document_id`). Used to deduplicate citations within a turn.
	ID string `json:"id"`

	// Relevance score of this source for the turn's query (the knowledge-base
	// similarity score). Higher is more relevant.
	Score float64 `json:"score"`

	// The retrieved chunk text that grounded the answer, truncated to a bounded
	// length for display.
	Snippet string `json:"snippet"`

	// Human-readable label for the source — typically the document's source path or,
	// for web-sourced docs, the URL/title.
	Title string `json:"title"`

	// Canonical link to the source, when one exists. For GitHub-sourced documents
	// this is the blob/issue URL stamped onto the document's `source` at ingest.
	// Absent for sources with no web location.
	URL *string `json:"url,omitempty,omitzero"`
}

type GeneralAgentResponse struct {
	// Estimated customer happiness for this turn (0 = very unhappy, 1 = very happy).
	CustomerHappinessScore float64 `json:"customerHappinessScore"`

	// Estimated degree to which the customer's needs were met (0 = not met, 1 = fully
	// met).
	NeedsSatisfactionScore float64 `json:"needsSatisfactionScore"`

	// One-sentence summary of what the user requested.
	RequestSummary string `json:"requestSummary"`

	// The agent's assessment of where the conversation stands after this turn.
	ResolutionStatus GeneralAgentResponseResolutionStatus `json:"resolutionStatus"`

	// Ordered text segments that together form the agent's reply. Clients may join
	// them or render each separately.
	ResponseParts []string `json:"responseParts"`

	// Ordered list of suggested follow-up actions the client UI may surface to the
	// user.
	SuggestedNextActions []string `json:"suggestedNextActions"`
}

type GeneralAgentResponseResolutionStatus string

type GetMessagesParams struct {
	SessionID string `json:"sessionId"`
	Limit     int    `json:"limit,omitempty"`
	Before    string `json:"before,omitempty"`
}

type GetMessagesRequest struct {
	// Action discriminator.
	Action string `json:"action"`

	// ISO 8601 cursor: return only messages created strictly before this timestamp.
	// Omit to start from the most recent message.
	Before *time.Time `json:"before,omitempty,omitzero"`

	// Maximum number of messages to return per page. Must be 1–100; defaults to 50.
	Limit int `json:"limit,omitempty,omitzero"`

	// Client-generated correlation ID echoed back on all related events.
	RequestID *string `json:"requestId,omitempty,omitzero"`

	// Session ID whose conversation messages to fetch.
	SessionID string `json:"sessionId"`
}

type GetMessagesResponse struct {
	// True if more messages exist before the oldest message in this page. Use the
	// oldest `createdAt` as the next `before` cursor.
	HasMore bool `json:"hasMore"`

	// Ordered list of messages (newest-first up to `limit`).
	Messages []ConversationMessage `json:"messages"`
}

type GetSessionParams struct {
	SessionID string `json:"sessionId"`
}

type GetSessionRequest struct {
	// Action discriminator.
	Action string `json:"action"`

	// Client-generated correlation ID echoed back on all related events.
	RequestID *string `json:"requestId,omitempty,omitzero"`

	// ID of the session to retrieve.
	SessionID string `json:"sessionId"`
}

type GetSessionResponse struct {
	// Agent ID.
	AgentID string `json:"agentId"`

	// Display name of the agent.
	AgentName string `json:"agentName"`

	// Participant ID for the agent in this session.
	AgentParticipantID string `json:"agentParticipantId"`

	// Conversation ID.
	ConversationID string `json:"conversationId"`

	// Session ID.
	SessionID string `json:"sessionId"`

	// Current lifecycle status of the session.
	Status *ResponseStatus `json:"status,omitempty,omitzero"`

	// smooth-operator thread identifier. Present when the session has an associated
	// workflow thread.
	ThreadID *string `json:"threadId,omitempty,omitzero"`

	// Participant ID for the user in this session.
	UserParticipantID string `json:"userParticipantId"`
}

type ImmediateResponse struct {
	// Action-specific response payload. For `create_conversation_session` and
	// `get_session`, this is the session descriptor. For `get_conversation_messages`,
	// this is the message page. For streaming `send_message`, this is typically empty
	// or contains only a minimal ack.
	Data ImmediateResponseData `json:"data"`

	// Human-readable status description (e.g. `Processing your request...`).
	Message *string `json:"message,omitempty,omitzero"`

	// Echoes the `requestId` from the originating action.
	RequestID *string `json:"requestId,omitempty,omitzero"`

	// HTTP-like status. 202 = accepted and processing; 200 = synchronous success
	// (non-streaming responses).
	Status *int `json:"status,omitempty,omitzero"`

	// Unix epoch milliseconds when the event was emitted.
	Timestamp *int `json:"timestamp,omitempty,omitzero"`

	// Event type discriminator.
	Type string `json:"type"`
}

type ImmediateResponseData map[string]interface{}

type Keepalive struct {
	// Keepalive payload.
	Data KeepaliveData `json:"data"`

	// The `requestId` of the in-flight request this keepalive is associated with.
	RequestID *string `json:"requestId,omitempty,omitzero"`

	// Unix epoch milliseconds when the keepalive was sent.
	Timestamp *int `json:"timestamp,omitempty,omitzero"`

	// Event type discriminator.
	Type string `json:"type"`
}

type KeepaliveData struct {
	// The request ID of the in-flight request this keepalive belongs to.
	RequestID string `json:"requestId"`
}

type Message struct {
	// Analytics data associated with this message (e.g. sentiment scores, token
	// counts).
	AnalyticsJSON *MessageAnalyticsJSON `json:"analyticsJson,omitempty,omitzero"`

	// The message payload.
	Content MessageContent `json:"content"`

	// The conversation this message belongs to.
	ConversationID MessageConversationID `json:"conversationId,omitempty,omitzero"`

	// ISO 8601 timestamp when the message was created.
	CreatedAt time.Time `json:"createdAt"`

	// Message direction relative to the platform: `inbound` = from user/external,
	// `outbound` = from agent/platform.
	Direction MessageDirection `json:"direction"`

	// ID assigned by an external platform (e.g. a Twilio SID or Messenger message
	// id).
	ExternalID MessageExternalID `json:"externalId,omitempty,omitzero"`

	// Abbreviated sender descriptor (wire shape used in API responses; full
	// participant data lives in domain/participant.schema.json).
	From *MessageFrom `json:"from,omitempty,omitzero"`

	// Unique message identifier.
	ID string `json:"id"`

	// Arbitrary key/value metadata attached to this message.
	MetadataJSON *MessageMetadataJSON `json:"metadataJson,omitempty,omitzero"`

	// The organization that owns this message.
	OrganizationID MessageOrganizationID `json:"organizationId,omitempty,omitzero"`

	// Abbreviated recipient descriptor.
	To *MessageTo `json:"to,omitempty,omitzero"`

	// ISO 8601 timestamp when the message was last updated.
	UpdatedAt MessageUpdatedAt `json:"updatedAt,omitempty,omitzero"`
}

type MessageAnalyticsJSON map[string]interface{}

type MessageContent struct {
	// Ordered list of content items that make up this message.
	Items []ContentItem `json:"items,omitempty,omitzero"`

	// Structured agent response payload. Shape varies by agent template.
	StructuredResponse *MessageContentStructuredResponse `json:"structuredResponse,omitempty,omitzero"`

	// Convenience flat-text representation of the message (populated for simple
	// text-only messages).
	Text MessageContentText `json:"text,omitempty,omitzero"`
}

type MessageContentStructuredResponse map[string]interface{}

type MessageContentText *string

type MessageConversationID *string

type MessageDirection string

type MessageExternalID *string

type MessageFrom struct {
	// Participant ID of the sender.
	ID string `json:"id"`

	// Display name of the sender.
	Name MessageFromName `json:"name,omitempty,omitzero"`

	// Participant type of the sender.
	Type string `json:"type"`
}

type MessageFromName *string

type MessageMetadataJSON map[string]interface{}

type MessageOrganizationID *string

type MessageTo struct {
	// Participant ID of the recipient.
	ID string `json:"id"`

	// Display name of the recipient.
	Name MessageToName `json:"name,omitempty,omitzero"`

	// Participant type of the recipient.
	Type string `json:"type"`
}

type MessageToName *string

type MessageTurn struct {
	// contains filtered or unexported fields
}

type MessageUpdatedAt *time.Time

type OTPInvalid struct {
	// Failure details.
	Data OTPInvalidData `json:"data"`

	// Echoes the `requestId` from the originating `verify_otp` action.
	RequestID *string `json:"requestId,omitempty,omitzero"`

	// Unix epoch milliseconds when the event was emitted.
	Timestamp *int `json:"timestamp,omitempty,omitzero"`

	// Event type discriminator.
	Type string `json:"type"`
}

type OTPInvalidData struct {
	// OTP invalid payload.
	Data OTPInvalidDataData `json:"data"`

	// The request ID this verification belongs to.
	RequestID string `json:"requestId"`
}

type OTPInvalidDataData struct {
	// How many more attempts the caller has before the OTP is locked. Zero means the
	// session is locked and a new OTP must be requested.
	AttemptsRemaining int `json:"attemptsRemaining"`

	// Machine-readable failure reason. Absent if the server cannot determine a
	// specific cause.
	Error *OTPInvalidDataDataError `json:"error,omitempty,omitzero"`

	// Human-readable failure message suitable for display in the verification UI.
	Message string `json:"message"`
}

type OTPInvalidDataDataError string

type OTPSent struct {
	// OTP send acknowledgement details.
	Data OTPSentData `json:"data"`

	// Echoes the `requestId` from the originating action.
	RequestID *string `json:"requestId,omitempty,omitzero"`

	// Unix epoch milliseconds when the event was emitted.
	Timestamp *int `json:"timestamp,omitempty,omitzero"`

	// Event type discriminator.
	Type string `json:"type"`
}

type OTPSentData struct {
	// Delivery details.
	Data OTPSentDataData `json:"data"`

	// The request ID this OTP delivery belongs to.
	RequestID string `json:"requestId"`
}

type OTPSentDataData struct {
	// The channel through which the OTP was delivered.
	Channel OTPSentDataDataChannel `json:"channel"`

	// Partially masked destination address for display in the UI (e.g.
	// `j***@example.com` or `+1 ***-***-4567`). Sufficient for the user to recognize
	// their own address without exposing it fully.
	MaskedDestination string `json:"maskedDestination"`
}

type OTPSentDataDataChannel string

type OTPVerificationRequired struct {
	// Verification prompt details.
	Data OTPVerificationRequiredData `json:"data"`

	// Echoes the `requestId` from the originating `send_message` action. Must be
	// included in the `verify_otp` reply.
	RequestID *string `json:"requestId,omitempty,omitzero"`

	// Unix epoch milliseconds when the event was emitted.
	Timestamp *int `json:"timestamp,omitempty,omitzero"`

	// Event type discriminator.
	Type string `json:"type"`
}

type OTPVerificationRequiredData struct {
	// Details about the authentication requirement.
	Data OTPVerificationRequiredDataData `json:"data"`

	// The request ID this verification belongs to.
	RequestID string `json:"requestId"`
}

type OTPVerificationRequiredDataData struct {
	// Human-readable description of the action requiring verification, suitable for
	// the consent UI.
	ActionDescription string `json:"actionDescription"`

	// Required authentication level. Common values: `email`, `sms`, `mfa`,
	// `end_user`, `admin`.
	AuthLevel string `json:"authLevel"`

	// Delivery channels available to send the OTP. The client should let the user
	// choose.
	AvailableChannels []OTPVerificationRequiredDataDataAvailableChannelsElem `json:"availableChannels"`

	// Opaque identifier of the tool invocation awaiting verification.
	ToolID string `json:"toolId"`
}

type OTPVerificationRequiredDataDataAvailableChannelsElem string

type OTPVerified struct {
	// Verification success details.
	Data OTPVerifiedData `json:"data"`

	// Echoes the `requestId` from the originating `verify_otp` action.
	RequestID *string `json:"requestId,omitempty,omitzero"`

	// Unix epoch milliseconds when the event was emitted.
	Timestamp *int `json:"timestamp,omitempty,omitzero"`

	// Event type discriminator.
	Type string `json:"type"`
}

type OTPVerifiedData struct {
	// Success payload.
	Data OTPVerifiedDataData `json:"data"`

	// The request ID this verification belongs to.
	RequestID string `json:"requestId"`
}

type OTPVerifiedDataData struct {
	// Short human-readable confirmation message (e.g. `Identity verified
	// successfully.`).
	Message string `json:"message"`
}

type Options struct {
	// Transport is the wire abstraction. Required (use NewWebSocketTransport for the
	// default, or a mock in tests).
	Transport Transport
	// GenerateRequestID overrides request ID generation. Defaults to "req-" + UUIDv4.
	GenerateRequestID func() string
	// TurnTimeout bounds a streaming send_message turn (see DefaultTurnTimeout).
	// Zero uses DefaultTurnTimeout; a negative value disables the turn timeout.
	TurnTimeout time.Duration
}

type Participant struct {
	// Browser fingerprint (ThumbmarkJS) for anonymous user identification.
	BrowserFingerprint ParticipantBrowserFingerprint `json:"browserFingerprint,omitempty,omitzero"`

	// Parsed browser / device metadata collected at session start.
	BrowserInfo *ParticipantBrowserInfo `json:"browserInfo,omitempty,omitzero"`

	// The conversation this participant belongs to.
	ConversationID string `json:"conversationId"`

	// ISO 8601 timestamp when the participant record was created.
	CreatedAt time.Time `json:"createdAt"`

	// Foreign key into the CRM contacts table if this participant has been matched.
	CrmContactID ParticipantCrmContactID `json:"crmContactId,omitempty,omitzero"`

	// Email address if known.
	Email ParticipantEmail `json:"email,omitempty,omitzero"`

	// External identity (e.g. Supabase auth user UUID) for authenticated
	// participants.
	ExternalID ParticipantExternalID `json:"externalId,omitempty,omitzero"`

	// Unique participant identifier.
	ID string `json:"id"`

	// Internal system identifier (e.g. agent UUID from the agents table).
	InternalID ParticipantInternalID `json:"internalId,omitempty,omitzero"`

	// Arbitrary key/value metadata attached to this participant.
	MetadataJSON ParticipantMetadataJSON `json:"metadataJson,omitempty,omitzero"`

	// Display name for this participant.
	Name string `json:"name"`

	// The organization that owns this participant record.
	OrganizationID string `json:"organizationId"`

	// Phone number in E.164 format if known.
	Phone ParticipantPhone `json:"phone,omitempty,omitzero"`

	// Participant role: `user` = end-user, `ai-agent` = smooth-operator agent,
	// `human-agent` = live support agent.
	Type ParticipantType `json:"type"`

	// ISO 8601 timestamp when the participant record was last updated.
	UpdatedAt time.Time `json:"updatedAt"`
}

type ParticipantBrowserFingerprint *string

type ParticipantBrowserInfo map[string]interface{}

type ParticipantCrmContactID *string

type ParticipantEmail *string

type ParticipantExternalID *string

type ParticipantInternalID *string

type ParticipantMetadataJSON map[string]interface{}

type ParticipantPhone *string

type ParticipantType string

type PingRequest struct {
	// Action discriminator.
	Action string `json:"action"`

	// Client-generated correlation ID echoed back in the `pong` event.
	RequestID *string `json:"requestId,omitempty,omitzero"`
}

type Pong struct {
	// Pong payload (mirrors top-level `timestamp` for clients that only inspect
	// `data`).
	Data *PongData `json:"data,omitempty,omitzero"`

	// Echoes the `requestId` from the originating `ping` action.
	RequestID *string `json:"requestId,omitempty,omitzero"`

	// Server-side Unix epoch milliseconds when the pong was emitted.
	Timestamp *int `json:"timestamp,omitempty,omitzero"`

	// Event type discriminator.
	Type string `json:"type"`
}

type PongData struct {
	// Server-side Unix epoch milliseconds.
	Timestamp int `json:"timestamp"`
}

type PongResponse struct {
	// Server-side Unix epoch milliseconds when the pong was sent.
	Timestamp int `json:"timestamp"`
}

type ProtocolError struct {
	Code      string
	Message   string
	RequestID string
}

type RequestAuthContext struct {
	// HMAC-SHA256 signature over `userId + timestamp` using a shared secret.
	Signature string `json:"signature"`

	// Unix epoch seconds when the HMAC was signed. Used for replay protection
	// (typical max age: 60s).
	Timestamp int `json:"timestamp"`

	// The user's identity claim.
	UserID string `json:"userId"`
}

type RequestMetadata map[string]interface{}

type ResponseStatus string

type SendMessageParams struct {
	SessionID string `json:"sessionId"`
	Message   string `json:"message"`
	// Stream controls whether incremental stream_chunk/stream_token events are sent.
	// nil leaves the field off the wire (server default = true).
	Stream *bool `json:"stream,omitempty"`
}

type SendMessageRequest struct {
	// Action discriminator.
	Action string `json:"action"`

	// The user's message text. Between 1 and 10 000 characters.
	Message string `json:"message"`

	// Client-generated correlation ID echoed back on all related events.
	RequestID *string `json:"requestId,omitempty,omitzero"`

	// Session ID returned by `create_conversation_session`.
	SessionID string `json:"sessionId"`

	// Whether to receive incremental `stream_chunk` and `stream_token` events.
	// Defaults to `true`. Set to `false` to receive only the final
	// `eventual_response`.
	Stream bool `json:"stream,omitempty,omitzero"`
}

type SendMessageResponse struct {
	// Human-readable reason when `needsEscalation` is true.
	EscalationReason *string `json:"escalationReason,omitempty,omitzero"`

	// ID of the agent's response message as persisted to the database.
	MessageID string `json:"messageId"`

	// True if the agent flagged this turn for human escalation.
	NeedsEscalation bool `json:"needsEscalation"`

	// Structured agent response.
	Response GeneralAgentResponse `json:"response"`
}

type ServerEvent struct {
	// Type is the event discriminator (`type` on the wire).
	Type EventType
	// RequestID echoes the originating action's requestId, when present.
	RequestID string
	// Status is the HTTP-like status code (0 if absent).
	Status int
	// Node is the workflow node name, present on stream_chunk events.
	Node string
	// Token is the streamed token text, present on stream_token events.
	Token string
	// Raw is the complete, undecoded event frame. Use the As* accessors to decode
	// it into the concrete generated type.
	Raw json.RawMessage
}

type Session struct {
	// The agent handling this session.
	AgentID string `json:"agentId"`

	// Human-readable display name of the agent.
	AgentName string `json:"agentName"`

	// The participant record representing the AI agent in this session.
	AgentParticipantID string `json:"agentParticipantId"`

	// The conversation this session is attached to.
	ConversationID string `json:"conversationId"`

	// ISO 8601 timestamp when the session was created.
	CreatedAt *time.Time `json:"createdAt,omitempty,omitzero"`

	// ISO 8601 timestamp when the session ended, or null if still active.
	EndedAt SessionEndedAt `json:"endedAt,omitempty,omitzero"`

	// ISO 8601 timestamp of the most recent activity (message, keepalive, etc.).
	LastActivityAt *time.Time `json:"lastActivityAt,omitempty,omitzero"`

	// Number of messages exchanged in this session.
	MessageCount *int `json:"messageCount,omitempty,omitzero"`

	// Arbitrary key/value metadata attached to this session (e.g. browser info,
	// campaign source).
	Metadata SessionMetadata `json:"metadata,omitempty,omitzero"`

	// Unique session identifier.
	SessionID string `json:"sessionId"`

	// Lifecycle status of the session.
	Status *SessionStatus `json:"status,omitempty,omitzero"`

	// smooth-operator workflow thread identifier. Used to resume agent state across
	// turns and process restarts. Stored as `langgraph_thread_id` in the database for
	// historical reasons.
	ThreadID string `json:"threadId"`

	// Cumulative token count consumed in this session.
	TokenCount *int `json:"tokenCount,omitempty,omitzero"`

	// ISO 8601 timestamp when the session was last updated.
	UpdatedAt *time.Time `json:"updatedAt,omitempty,omitzero"`

	// The participant record representing the end user in this session.
	UserParticipantID string `json:"userParticipantId"`
}

type SessionEndedAt *time.Time

type SessionMetadata map[string]interface{}

type SessionStatus string

type StreamChunk struct {
	// The per-node state snapshot.
	Data StreamChunkData `json:"data"`

	// Name of the workflow node that just completed and produced this chunk.
	Node *string `json:"node,omitempty,omitzero"`

	// Echoes the `requestId` from the originating `send_message` action.
	RequestID *string `json:"requestId,omitempty,omitzero"`

	// Unix epoch milliseconds when the event was emitted.
	Timestamp *int `json:"timestamp,omitempty,omitzero"`

	// Event type discriminator.
	Type string `json:"type"`
}

type StreamChunkData struct {
	// Reserved for future use. When true, this is the last `stream_chunk` for the
	// request. Currently clients should use `eventual_response` to detect stream
	// completion.
	Done *bool `json:"done,omitempty,omitzero"`

	// Name of the workflow node that produced this state snapshot.
	Node string `json:"node"`

	// The request ID this chunk belongs to.
	RequestID string `json:"requestId"`

	// Filtered subset of the node's output state exposed to the client. Only
	// safe-to-expose fields are included; server-internal state is stripped.
	State StreamChunkDataState `json:"state"`
}

type StreamChunkDataState struct {
	// Non-null when the workflow has paused awaiting OTP verification. Clients should
	// surface an OTP input UI.
	PendingOTPVerification *StreamChunkDataStatePendingOTPVerification `json:"pendingOtpVerification,omitempty,omitzero"`

	// Non-null when the workflow has paused awaiting user confirmation of a write
	// operation. Clients should surface a confirmation UI.
	PendingWriteConfirmation *StreamChunkDataStatePendingWriteConfirmation `json:"pendingWriteConfirmation,omitempty,omitzero"`

	// Unstructured LLM output from this node, if any.
	RawResponse interface{} `json:"rawResponse,omitempty,omitzero"`

	// Parsed structured response from this node, if any.
	StructuredResponse interface{} `json:"structuredResponse,omitempty,omitzero"`
}

type StreamChunkDataStatePendingOTPVerification map[string]interface{}

type StreamChunkDataStatePendingWriteConfirmation map[string]interface{}

type StreamToken struct {
	// Token event payload.
	Data StreamTokenData `json:"data"`

	// Echoes the `requestId` from the originating `send_message` action.
	RequestID *string `json:"requestId,omitempty,omitzero"`

	// Unix epoch milliseconds when the event was emitted.
	Timestamp *int `json:"timestamp,omitempty,omitzero"`

	// The raw token text. Also present inside `data.token` for consumers that only
	// inspect `data`.
	Token *string `json:"token,omitempty,omitzero"`

	// Event type discriminator.
	Type string `json:"type"`
}

type StreamTokenData struct {
	// The request ID this token belongs to.
	RequestID string `json:"requestId"`

	// The raw token text.
	Token string `json:"token"`
}

type Transport interface {
	// Connect opens the underlying connection. It must return once the transport is
	// ready to Send/Receive, or with an error if it cannot connect.
	Connect(ctx context.Context) error
	// Send writes a single serialized frame. It returns an error if the transport is
	// not open.
	Send(frame []byte) error
	// Receive returns the channel on which inbound frames are delivered. The channel
	// is closed when the transport closes (cleanly or on error).
	Receive() <-chan []byte
	// Close shuts the transport down. Subsequent Sends return an error and Receive's
	// channel is closed.
	Close() error
	// Err returns the terminal error that closed the transport, if any. It returns
	// nil for a clean close.
	Err() error
}

type TurnTimeoutError struct {
	RequestID string
	Timeout   time.Duration
}

type UnknownEventError struct{ Type string }

type Validator struct {
	// contains filtered or unexported fields
}

type VerifyOTPParams struct {
	SessionID string `json:"sessionId"`
	// RequestID must match the otp_verification_required event being answered.
	RequestID string `json:"requestId"`
	Code      string `json:"code"`
}

type VerifyOTPRequest struct {
	// Action discriminator.
	Action string `json:"action"`

	// The one-time password code entered by the user.
	Code string `json:"code"`

	// Must match the `requestId` from the `otp_verification_required` event being
	// responded to.
	RequestID string `json:"requestId"`

	// Session ID of the paused session.
	SessionID string `json:"sessionId"`
}

type VerifyOTPResponse map[string]interface{}

type WebSocketTransport struct {
	// contains filtered or unexported fields
}

type WriteConfirmationRequired struct {
	// Confirmation prompt details.
	Data WriteConfirmationRequiredData `json:"data"`

	// Echoes the `requestId` from the originating `send_message` action. Must be
	// included in the `confirm_tool_action` reply.
	RequestID *string `json:"requestId,omitempty,omitzero"`

	// Unix epoch milliseconds when the event was emitted.
	Timestamp *int `json:"timestamp,omitempty,omitzero"`

	// Event type discriminator.
	Type string `json:"type"`
}

type WriteConfirmationRequiredData struct {
	// Details about the pending write that the user must approve or reject.
	Data WriteConfirmationRequiredDataData `json:"data"`

	// The request ID this confirmation belongs to.
	RequestID string `json:"requestId"`
}

type WriteConfirmationRequiredDataData struct {
	// Human-readable description of the action the agent wants to perform, suitable
	// for displaying in a confirmation dialog (e.g. `Delete contact John Doe
	// (john@example.com)`).
	ActionDescription string `json:"actionDescription"`

	// Opaque identifier of the tool invocation awaiting confirmation. Provided for
	// correlation; clients do not need to parse or display this.
	ToolID string `json:"toolId"`
}