l-ai-chat-proto/chat.proto

syntax = "proto3";

package chat;

option go_package = "git.be.kaien.ru/l-ai/l-ai-chat-proto/proto";

import "google/protobuf/timestamp.proto";

// ChatService is the canonical API of the l-ai-chat Live Chat service.
// Chat Service is the single source of truth for messages; clients (Web UI,
// Telegram bot, agents) send and read messages through it.
service ChatService {
  // ListTopics returns all topics in stable (creation) order.
  rpc ListTopics(ListTopicsRequest) returns (ListTopicsResponse);

  // GetTopic returns one topic by id or slug.
  rpc GetTopic(GetTopicRequest) returns (Topic);

  // CreateTopic creates a new topic. Slug must be unique.
  rpc CreateTopic(CreateTopicRequest) returns (Topic);

  // PostMessage appends a message to a topic. Repeated calls with the same
  // (author_id, idempotency_key) must not create a second message; the
  // original message is returned with duplicated=true instead.
  rpc PostMessage(PostMessageRequest) returns (PostMessageResponse);

  // GetMessage returns a single message by id.
  rpc GetMessage(GetMessageRequest) returns (Message);

  // History returns messages of a topic, paginated by sequence (no offset
  // pagination). Use before_sequence for newest-first backward paging or
  // after_sequence for oldest-first forward paging; at most one may be set.
  rpc History(HistoryRequest) returns (HistoryResponse);

  // Subscribe streams new messages of a topic to a consumer. The consumer is
  // expected to Acknowledge the messages it processed (at-least-once).
  // NOTE: stream delivery is implemented in a later stage.
  rpc Subscribe(SubscribeRequest) returns (stream Message);

  // Acknowledge advances the durable delivery cursor of a consumer in a
  // topic. Cursors are monotonic: the stored value never moves backwards.
  rpc Acknowledge(AcknowledgeRequest) returns (AcknowledgeResponse);
}

// AuthorType is the kind of identity a message author has. HUMAN covers
// internal users (the same author_id across Web and Telegram), AGENT covers
// l-ai agents, SYSTEM covers service-internal messages, INTEGRATION covers
// bridge/external systems.
enum AuthorType {
  AUTHOR_TYPE_UNSPECIFIED = 0;
  AUTHOR_TYPE_HUMAN = 1;
  AUTHOR_TYPE_AGENT = 2;
  AUTHOR_TYPE_SYSTEM = 3;
  AUTHOR_TYPE_INTEGRATION = 4;
}

// MessageSource is the channel through which a message entered the system.
enum MessageSource {
  MESSAGE_SOURCE_UNSPECIFIED = 0;
  MESSAGE_SOURCE_WEB = 1;
  MESSAGE_SOURCE_TELEGRAM = 2;
  MESSAGE_SOURCE_AGENT = 3;
  MESSAGE_SOURCE_SYSTEM = 4;
}

message Topic {
  string id = 1; // UUID
  string slug = 2; // stable, unique, e.g. "security"
  string display_name = 3; // e.g. "Security"
  google.protobuf.Timestamp created_at = 4;
}

message Message {
  string id = 1; // UUID, canonical message id
  int64 sequence = 2; // server-assigned monotonic sequence (ordering + durable cursor)
  string topic_id = 3; // UUID
  string author_id = 4; // stable identity of the author (UUID)
  AuthorType author_type = 5;
  MessageSource source = 6;
  string content = 7;
  optional string reply_to_message_id = 8; // parent message when this is a reply
  string root_message_id = 9; // root of the reply chain (== id for non-replies)
  int32 reply_depth = 10; // 0 for non-replies, parent depth + 1 for replies; hard max 20
  google.protobuf.Timestamp created_at = 11;
}

message ListTopicsRequest {}

message ListTopicsResponse {
  repeated Topic topics = 1;
}

message GetTopicRequest {
  oneof selector {
    string id = 1;
    string slug = 2;
  }
}

message CreateTopicRequest {
  string slug = 1;
  string display_name = 2;
}

message PostMessageRequest {
  string topic_id = 1;
  string author_id = 2;
  AuthorType author_type = 3;
  MessageSource source = 4;
  string content = 5;
  optional string reply_to_message_id = 6;
  // Idempotency key: retrying PostMessage with the same author_id and key
  // returns the original message instead of creating a duplicate.
  string idempotency_key = 7;
}

message PostMessageResponse {
  Message message = 1;
  bool duplicated = 2; // true when an idempotent replay returned an existing message
}

message GetMessageRequest {
  string message_id = 1;
}

message HistoryRequest {
  string topic_id = 1;
  // Backward paging: return messages with sequence < before_sequence,
  // newest first. Mutually exclusive with after_sequence.
  int64 before_sequence = 2;
  // Forward paging: return messages with sequence > after_sequence,
  // oldest first. Mutually exclusive with before_sequence.
  int64 after_sequence = 3;
  // Maximum number of messages to return (server may cap it).
  int32 limit = 4;
}

message HistoryResponse {
  repeated Message messages = 1;
  // true when more messages exist in the requested direction.
  bool has_more = 2;
}

message SubscribeRequest {
  string consumer_id = 1; // stable identity of the consumer/agent
  string topic_id = 2;
}

message AcknowledgeRequest {
  string consumer_id = 1;
  string topic_id = 2;
  int64 last_ack_sequence = 3; // highest sequence processed by the consumer
}

message AcknowledgeResponse {
  int64 last_ack_sequence = 1; // the cursor as stored (never lower than before)
}