spec

type Conversation struct {
	SchemaVersion string    `json:"schemaVersion"`
	ID            string    `json:"id"`
	Title         string    `json:"title,omitempty"`
	CreatedAt     time.Time `json:"createdAt"`
	ModifiedAt    time.Time `json:"modifiedAt"`

	// Ordered list of turns (messages) in the transcript.
	Messages []ConversationMessage `json:"messages"`

	// Extra metadata for your app (folders, tags, project, etc.).
	Meta map[string]any `json:"meta,omitempty"`
}

type ConversationListItem struct {
	ID             string     `json:"id"`
	SanatizedTitle string     `json:"sanatizedTitle"`
	ModifiedAt     *time.Time `json:"modifiedAt"`
}

type ConversationMessage struct {
	ID        string                 `json:"id"`
	CreatedAt time.Time              `json:"createdAt"`
	Role      inferenceSpec.RoleEnum `json:"role"`
	Status    inferenceSpec.Status   `json:"status,omitzero"`

	// Default model configuration for this turn. This can be empty and would mean that model param have been carried
	// over from previous messages. Same for model ref.
	ModelParam     *inferenceSpec.ModelParam       `json:"modelParam,omitempty"`
	ModelPresetRef *modelpresetSpec.ModelPresetRef `json:"modelPresetRef,omitempty"`

	// Canonical, lossless events for this turn, in the order they occurred.
	//
	// For a user turn, you typically have exactly one InputKindInputMessage
	// entry in Inputs, possibly preceded by earlier tool outputs, etc.
	// For an assistant turn, you typically have:
	//   - one or more OutputKindOutputMessage entries,
	//   - zero or more OutputKindReasoningMessage entries,
	//   - zero or more tool call / web-search events, etc.
	Inputs  []inferenceSpec.InputUnion  `json:"inputs,omitempty"`
	Outputs []inferenceSpec.OutputUnion `json:"outputs,omitempty"`

	// Tool choices that were *available* when this turn ran.
	// For the next completion, the app can choose to reuse or override these.
	ToolChoices      []inferenceSpec.ToolChoice `json:"toolChoices,omitempty"`
	ToolStoreChoices []toolSpec.ToolStoreChoice `json:"toolStoreChoices,omitempty"`

	MCPContext           *mcpSpec.MCPConversationContext    `json:"mcpContext,omitempty"`
	MCPAppContextUpdates []mcpSpec.MCPAppModelContextUpdate `json:"mcpAppContextUpdates,omitempty"`

	// Attachments that backed this turn's user input (files, URLs, etc).
	// These are ref attachments; ContentBlock may or may not be hydrated.
	Attachments      []attachment.Attachment `json:"attachments,omitempty"`
	EnabledSkillRefs []skillSpec.SkillRef    `json:"enabledSkillRefs,omitempty"`
	ActiveSkillRefs  []skillSpec.SkillRef    `json:"activeSkillRefs,omitempty"`

	// Usage / error info from the model/provider for this turn
	// (usually attached to assistant turns).
	Usage        *inferenceSpec.Usage `json:"usage,omitempty"`
	Error        *inferenceSpec.Error `json:"error,omitempty"`
	DebugDetails any                  `json:"debugDetails,omitempty"`

	// Arbitrary UI/app metadata (tags, pinned, read state, etc.).
	Meta map[string]any `json:"meta,omitempty"`
}

type DeleteConversationRequest struct {
	ID    string `path:"id" required:"true"`
	Title string `          required:"true" query:"title"`
}

type DeleteConversationResponse struct{}

type GetConversationRequest struct {
	ID         string `path:"id" required:"true"`
	Title      string `          required:"true" query:"title"`
	ForceFetch bool   `                          query:"forceFetch"`
}

type GetConversationResponse struct {
	Body *Conversation
}

type ListConversationsRequest struct {
	PageSize  int    `query:"pageSize"`
	PageToken string `query:"pageToken"`
}

type ListConversationsResponse struct {
	Body *ListConversationsResponseBody
}

type ListConversationsResponseBody struct {
	ConversationListItems []ConversationListItem `json:"conversationListItems"`
	NextPageToken         *string                `json:"nextPageToken,omitempty"`
}

type PutConversationRequest struct {
	ID   string `path:"id" required:"true"`
	Body *PutConversationRequestBody
}

type PutConversationRequestBody struct {
	Title      string                `json:"title"          required:"true"`
	CreatedAt  time.Time             `json:"createdAt"      required:"true"`
	ModifiedAt time.Time             `json:"modifiedAt"     required:"true"`
	Messages   []ConversationMessage `json:"messages"       required:"true"`
	Meta       map[string]any        `json:"meta,omitempty"`
}

type PutConversationResponse struct{}

type PutMessagesToConversationRequest struct {
	ID   string `path:"id" required:"true"`
	Body *PutMessagesToConversationRequestBody
}

type PutMessagesToConversationRequestBody struct {
	Title    string                `json:"title"    required:"true"`
	Messages []ConversationMessage `json:"messages" required:"true"`
}

type PutMessagesToConversationResponse struct{}

type SearchConversationsRequest struct {
	Query     string `query:"q"         required:"true"`
	PageToken string `query:"pageToken"`
	PageSize  int    `query:"pageSize"`
}

type SearchConversationsResponse struct {
	Body *SearchConversationsResponseBody
}

type SearchConversationsResponseBody struct {
	ConversationListItems []ConversationListItem `json:"conversationListItems"`
	NextPageToken         *string                `json:"nextPageToken,omitempty"`
}