Add ResolveLinkedAccountByUsername to UsersService

Callers that only know how a person is addressed in chat cannot use the
id-based lookup. Same fail-closed identity rule: an ambiguous username
fails rather than resolving to a guessed user, because acting on the wrong
one can mean phoning someone who never asked to be called.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

ai.proto

@@ -15,6 +15,36 @@ message AIRequest {
   int64 telegram_user_id = 7; // Telegram user ID для применения пользовательских настроек (стиль ответа)
   int64 steam_user_id = 8; // SteamID64 отправителя для живых Steam-диалогов (l-ai-steam) - тот же "сигнал живого чата", что telegram_user_id, для второй платформы
   bool supports_deferred = 9; // Клиент умеет обрабатывать status=PENDING + GetAnswerJob (async тяжёлые тулзы). Старые клиенты не ставят — тяжёлые тулзы исполняются синхронно, как раньше.
+  // Структурированные воспоминания, которые клиент уже вложил в text (для debug-trace).
+  // Core сохраняет их as-is на ai_response_traces — не перезапрашивает memories-сервис.
+  repeated UsedMemory used_memories = 10;
+  // Raw user message for intent classification (no history/memories/tools).
+  // Live chat clients (Telegram/Steam) send this; when empty, image intent
+  // detection is skipped and the request is treated as normal chat.
+  string user_message = 11;
+  // Optional image attachments for vision models (photo/sticker/GIF frame).
+  // When non-empty, GenerateAnswer routes to LLM_VISION_MODEL and builds a
+  // multimodal user message; image-generation intent is skipped.
+  repeated InputImage images = 12;
+}
+
+// InputImage — one vision attachment (raw bytes, not base64).
+message InputImage {
+  bytes data = 1;        // raw image bytes (jpeg/png/webp/gif)
+  string mime_type = 2;  // e.g. image/jpeg
+  string source = 3;     // optional client hint: photo, sticker, animation, reply_photo, …
+}
+
+// UsedMemory — снимок одного воспоминания, участвовавшего в генерации ответа.
+message UsedMemory {
+  int64 id = 1;            // ID в l-ai-memories (для будущего delete с debug-страницы)
+  int64 user_id = 2;
+  string username = 3;
+  string key = 4;
+  string value = 5;
+  string category = 6;
+  string priority = 7;
+  string source_label = 8; // контекст от клиента, напр. "автор сообщения (@nick)"
 }
 
 // AnswerGenerationOptions содержит дополнительные опции для генерации ответа
@@ -22,6 +52,13 @@ message AnswerGenerationOptions {
   bool include_user_memories = 1; // Включить воспоминания о пользователе в промпт
 }
 
+// ResponseKind — тип синхронного ответа GenerateAnswer (кроме deferred jobs).
+enum ResponseKind {
+  RESPONSE_KIND_UNSPECIFIED = 0; // трактуется как TEXT (обратная совместимость)
+  RESPONSE_KIND_TEXT = 1;        // content — текстовый ответ
+  RESPONSE_KIND_IMAGE = 2;       // image_base64 — сгенерированное изображение
+}
+
 // AIResponse содержит ответ от AI модели
 message AIResponse {
   string content = 1;        // Текст ответа (при status=PENDING — interim-сообщение)
@@ -31,6 +68,11 @@ message AIResponse {
   AnswerStatus status = 5;   // COMPLETE (или UNSPECIFIED для старых клиентов) — content финальный;
                              // PENDING — запущена долгая job, content это interim, финал тянуть через GetAnswerJob(job_id)
   string job_id = 6;         // Идентификатор отложенной job (только при status=PENDING)
+  string response_id = 7;    // UUID (hex) debug-trace; доступен уже при PENDING
+  ResponseKind kind = 8;     // TEXT (default) или IMAGE
+  string image_base64 = 9;   // base64-encoded image bytes when kind=IMAGE
+  string image_mime_type = 10; // e.g. image/png when kind=IMAGE
+  string image_prompt = 11;  // final Muse Image prompt when kind=IMAGE (for client-side history)
 }
 
 // AnswerStatus описывает, готов ли ответ синхронно или отложен в job.
@@ -66,6 +108,45 @@ message AnswerJobResponse {
   string content = 2;      // финальный ответ, когда DONE
   string error = 3;        // причина, когда FAILED
   double duration_ms = 4;  // суммарное время генерации, когда DONE
+  // Authoritative usage завершённой deferred RunAgent job — тот же счётчик, что
+  // возвращает synchronous RunAgent (реальные iterations/tool calls core, не
+  // self-reported из ответа модели). Для legacy GenerateAnswer jobs не заполняется.
+  AgentUsage agent_usage = 5;
+  string response_id = 6;  // тот же debug-trace id, что в AIResponse при PENDING
+}
+
+// ToolCallTrace — один вызов тула во время GenerateAnswer (args + результат для модели).
+message ToolCallTrace {
+  string call_id = 1;
+  string name = 2;
+  string arguments_json = 3;
+  string result = 4;
+  string error = 5;
+  bool deferred = 6; // тяжёлый тул через l-evolver
+}
+
+// GetAIResponseTraceRequest — запрос debug-снимка генерации по UUID.
+message GetAIResponseTraceRequest {
+  string id = 1; // response_id (hex UUID без дефисов)
+}
+
+// GetAIResponseTraceResponse — снимок того, что ушло в модель / вернулось.
+message GetAIResponseTraceResponse {
+  string id = 1;
+  string bot_username = 2;
+  string model_name = 3;
+  int64 telegram_user_id = 4;
+  int64 global_user_id = 5;
+  string system_prompt = 6;
+  string user_prompt = 7;
+  repeated UsedMemory memories = 8;
+  repeated ToolCallTrace tool_calls = 9;
+  string response = 10;
+  string reasoning_content = 11;
+  string error = 12;
+  double duration_ms = 13;
+  int64 created_at_unix = 14;
+  bool found = 15; // false — нет такого id / истёк TTL
 }
 
 // CreateSessionRequest для создания новой AI сессии
@@ -236,4 +317,7 @@ service AIService {
   // GetAnswerJob возвращает статус отложенной генерации ответа (когда GenerateAnswer
   // вернул status=PENDING). Клиент поллит его до DONE/FAILED и постит финал.
   rpc GetAnswerJob(GetAnswerJobRequest) returns (AnswerJobResponse);
+
+  // GetAIResponseTrace возвращает debug-снимок генерации (промпты, memories, tool calls).
+  rpc GetAIResponseTrace(GetAIResponseTraceRequest) returns (GetAIResponseTraceResponse);
 }

ai_grpc.pb.go

@@ -1,7 +1,7 @@
 // Code generated by protoc-gen-go-grpc. DO NOT EDIT.
 // versions:
-// - protoc-gen-go-grpc v1.6.1
-// - protoc             v7.34.0
+// - protoc-gen-go-grpc v1.6.2
+// - protoc             v7.36.0
 // source: ai.proto
 
 package proto
@@ -27,6 +27,7 @@ const (
 	AIService_CreateSession_FullMethodName      = "/ai.AIService/CreateSession"
 	AIService_AskInSession_FullMethodName       = "/ai.AIService/AskInSession"
 	AIService_GetAnswerJob_FullMethodName       = "/ai.AIService/GetAnswerJob"
+	AIService_GetAIResponseTrace_FullMethodName = "/ai.AIService/GetAIResponseTrace"
 )
 
 // AIServiceClient is the client API for AIService service.
@@ -53,6 +54,8 @@ type AIServiceClient interface {
 	// GetAnswerJob возвращает статус отложенной генерации ответа (когда GenerateAnswer
 	// вернул status=PENDING). Клиент поллит его до DONE/FAILED и постит финал.
 	GetAnswerJob(ctx context.Context, in *GetAnswerJobRequest, opts ...grpc.CallOption) (*AnswerJobResponse, error)
+	// GetAIResponseTrace возвращает debug-снимок генерации (промпты, memories, tool calls).
+	GetAIResponseTrace(ctx context.Context, in *GetAIResponseTraceRequest, opts ...grpc.CallOption) (*GetAIResponseTraceResponse, error)
 }
 
 type aIServiceClient struct {
@@ -143,6 +146,16 @@ func (c *aIServiceClient) GetAnswerJob(ctx context.Context, in *GetAnswerJobRequ
 	return out, nil
 }
 
+func (c *aIServiceClient) GetAIResponseTrace(ctx context.Context, in *GetAIResponseTraceRequest, opts ...grpc.CallOption) (*GetAIResponseTraceResponse, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(GetAIResponseTraceResponse)
+	err := c.cc.Invoke(ctx, AIService_GetAIResponseTrace_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
 // AIServiceServer is the server API for AIService service.
 // All implementations must embed UnimplementedAIServiceServer
 // for forward compatibility.
@@ -167,6 +180,8 @@ type AIServiceServer interface {
 	// GetAnswerJob возвращает статус отложенной генерации ответа (когда GenerateAnswer
 	// вернул status=PENDING). Клиент поллит его до DONE/FAILED и постит финал.
 	GetAnswerJob(context.Context, *GetAnswerJobRequest) (*AnswerJobResponse, error)
+	// GetAIResponseTrace возвращает debug-снимок генерации (промпты, memories, tool calls).
+	GetAIResponseTrace(context.Context, *GetAIResponseTraceRequest) (*GetAIResponseTraceResponse, error)
 	mustEmbedUnimplementedAIServiceServer()
 }
 
@@ -201,6 +216,9 @@ func (UnimplementedAIServiceServer) AskInSession(context.Context, *AskInSessionR
 func (UnimplementedAIServiceServer) GetAnswerJob(context.Context, *GetAnswerJobRequest) (*AnswerJobResponse, error) {
 	return nil, status.Error(codes.Unimplemented, "method GetAnswerJob not implemented")
 }
+func (UnimplementedAIServiceServer) GetAIResponseTrace(context.Context, *GetAIResponseTraceRequest) (*GetAIResponseTraceResponse, error) {
+	return nil, status.Error(codes.Unimplemented, "method GetAIResponseTrace not implemented")
+}
 func (UnimplementedAIServiceServer) mustEmbedUnimplementedAIServiceServer() {}
 func (UnimplementedAIServiceServer) testEmbeddedByValue()                   {}
 
@@ -366,6 +384,24 @@ func _AIService_GetAnswerJob_Handler(srv interface{}, ctx context.Context, dec f
 	return interceptor(ctx, in, info, handler)
 }
 
+func _AIService_GetAIResponseTrace_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(GetAIResponseTraceRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(AIServiceServer).GetAIResponseTrace(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: AIService_GetAIResponseTrace_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(AIServiceServer).GetAIResponseTrace(ctx, req.(*GetAIResponseTraceRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
 // AIService_ServiceDesc is the grpc.ServiceDesc for AIService service.
 // It's only intended for direct use with grpc.RegisterService,
 // and not to be introspected or modified (even as a copy)
@@ -405,6 +441,10 @@ var AIService_ServiceDesc = grpc.ServiceDesc{
 			MethodName: "GetAnswerJob",
 			Handler:    _AIService_GetAnswerJob_Handler,
 		},
+		{
+			MethodName: "GetAIResponseTrace",
+			Handler:    _AIService_GetAIResponseTrace_Handler,
+		},
 	},
 	Streams:  []grpc.StreamDesc{},
 	Metadata: "ai.proto",

users.pb.go

@@ -1,7 +1,7 @@
 // Code generated by protoc-gen-go. DO NOT EDIT.
 // versions:
 // 	protoc-gen-go v1.36.11
-// 	protoc        v7.34.0
+// 	protoc        (unknown)
 // source: users.proto
 
 package proto
@@ -711,6 +711,172 @@ func (x *GetLinkedAccountsResponse) GetAccounts() []*LinkedAccount {
 	return nil
 }
 
+type ResolveLinkedAccountRequest struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Platform      string                 `protobuf:"bytes,1,opt,name=platform,proto3" json:"platform,omitempty"`
+	AccountId     string                 `protobuf:"bytes,2,opt,name=account_id,json=accountId,proto3" json:"account_id,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *ResolveLinkedAccountRequest) Reset() {
+	*x = ResolveLinkedAccountRequest{}
+	mi := &file_users_proto_msgTypes[12]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *ResolveLinkedAccountRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ResolveLinkedAccountRequest) ProtoMessage() {}
+
+func (x *ResolveLinkedAccountRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_users_proto_msgTypes[12]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use ResolveLinkedAccountRequest.ProtoReflect.Descriptor instead.
+func (*ResolveLinkedAccountRequest) Descriptor() ([]byte, []int) {
+	return file_users_proto_rawDescGZIP(), []int{12}
+}
+
+func (x *ResolveLinkedAccountRequest) GetPlatform() string {
+	if x != nil {
+		return x.Platform
+	}
+	return ""
+}
+
+func (x *ResolveLinkedAccountRequest) GetAccountId() string {
+	if x != nil {
+		return x.AccountId
+	}
+	return ""
+}
+
+type ResolveLinkedAccountByUsernameRequest struct {
+	state    protoimpl.MessageState `protogen:"open.v1"`
+	Platform string                 `protobuf:"bytes,1,opt,name=platform,proto3" json:"platform,omitempty"`
+	// Username without a leading "@"; matched case-insensitively, the way
+	// people write it in chat.
+	Username      string `protobuf:"bytes,2,opt,name=username,proto3" json:"username,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *ResolveLinkedAccountByUsernameRequest) Reset() {
+	*x = ResolveLinkedAccountByUsernameRequest{}
+	mi := &file_users_proto_msgTypes[13]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *ResolveLinkedAccountByUsernameRequest) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ResolveLinkedAccountByUsernameRequest) ProtoMessage() {}
+
+func (x *ResolveLinkedAccountByUsernameRequest) ProtoReflect() protoreflect.Message {
+	mi := &file_users_proto_msgTypes[13]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use ResolveLinkedAccountByUsernameRequest.ProtoReflect.Descriptor instead.
+func (*ResolveLinkedAccountByUsernameRequest) Descriptor() ([]byte, []int) {
+	return file_users_proto_rawDescGZIP(), []int{13}
+}
+
+func (x *ResolveLinkedAccountByUsernameRequest) GetPlatform() string {
+	if x != nil {
+		return x.Platform
+	}
+	return ""
+}
+
+func (x *ResolveLinkedAccountByUsernameRequest) GetUsername() string {
+	if x != nil {
+		return x.Username
+	}
+	return ""
+}
+
+type ResolveLinkedAccountResponse struct {
+	state         protoimpl.MessageState `protogen:"open.v1"`
+	Linked        bool                   `protobuf:"varint,1,opt,name=linked,proto3" json:"linked,omitempty"`
+	GlobalUserId  int64                  `protobuf:"varint,2,opt,name=global_user_id,json=globalUserId,proto3" json:"global_user_id,omitempty"`
+	DisplayName   string                 `protobuf:"bytes,3,opt,name=display_name,json=displayName,proto3" json:"display_name,omitempty"`
+	unknownFields protoimpl.UnknownFields
+	sizeCache     protoimpl.SizeCache
+}
+
+func (x *ResolveLinkedAccountResponse) Reset() {
+	*x = ResolveLinkedAccountResponse{}
+	mi := &file_users_proto_msgTypes[14]
+	ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+	ms.StoreMessageInfo(mi)
+}
+
+func (x *ResolveLinkedAccountResponse) String() string {
+	return protoimpl.X.MessageStringOf(x)
+}
+
+func (*ResolveLinkedAccountResponse) ProtoMessage() {}
+
+func (x *ResolveLinkedAccountResponse) ProtoReflect() protoreflect.Message {
+	mi := &file_users_proto_msgTypes[14]
+	if x != nil {
+		ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x))
+		if ms.LoadMessageInfo() == nil {
+			ms.StoreMessageInfo(mi)
+		}
+		return ms
+	}
+	return mi.MessageOf(x)
+}
+
+// Deprecated: Use ResolveLinkedAccountResponse.ProtoReflect.Descriptor instead.
+func (*ResolveLinkedAccountResponse) Descriptor() ([]byte, []int) {
+	return file_users_proto_rawDescGZIP(), []int{14}
+}
+
+func (x *ResolveLinkedAccountResponse) GetLinked() bool {
+	if x != nil {
+		return x.Linked
+	}
+	return false
+}
+
+func (x *ResolveLinkedAccountResponse) GetGlobalUserId() int64 {
+	if x != nil {
+		return x.GlobalUserId
+	}
+	return 0
+}
+
+func (x *ResolveLinkedAccountResponse) GetDisplayName() string {
+	if x != nil {
+		return x.DisplayName
+	}
+	return ""
+}
+
 var File_users_proto protoreflect.FileDescriptor
 
 const file_users_proto_rawDesc = "" +
@@ -768,7 +934,18 @@ const file_users_proto_rawDesc = "" +
 	"\x0eglobal_user_id\x18\x01 \x01(\x03R\fglobalUserId\x12\x1a\n" +
 	"\bplatform\x18\x02 \x01(\tR\bplatform\"M\n" +
 	"\x19GetLinkedAccountsResponse\x120\n" +
-	"\baccounts\x18\x01 \x03(\v2\x14.users.LinkedAccountR\baccounts2\xe9\x05\n" +
+	"\baccounts\x18\x01 \x03(\v2\x14.users.LinkedAccountR\baccounts\"X\n" +
+	"\x1bResolveLinkedAccountRequest\x12\x1a\n" +
+	"\bplatform\x18\x01 \x01(\tR\bplatform\x12\x1d\n" +
+	"\n" +
+	"account_id\x18\x02 \x01(\tR\taccountId\"_\n" +
+	"%ResolveLinkedAccountByUsernameRequest\x12\x1a\n" +
+	"\bplatform\x18\x01 \x01(\tR\bplatform\x12\x1a\n" +
+	"\busername\x18\x02 \x01(\tR\busername\"\x7f\n" +
+	"\x1cResolveLinkedAccountResponse\x12\x16\n" +
+	"\x06linked\x18\x01 \x01(\bR\x06linked\x12$\n" +
+	"\x0eglobal_user_id\x18\x02 \x01(\x03R\fglobalUserId\x12!\n" +
+	"\fdisplay_name\x18\x03 \x01(\tR\vdisplayName2\xbf\a\n" +
 	"\fUsersService\x12E\n" +
 	"\x10CreateGlobalUser\x12\x1e.users.CreateGlobalUserRequest\x1a\x11.users.GlobalUser\x12?\n" +
 	"\rGetGlobalUser\x12\x1b.users.GetGlobalUserRequest\x1a\x11.users.GlobalUser\x12M\n" +
@@ -778,7 +955,9 @@ const file_users_proto_rawDesc = "" +
 	"\rUnlinkAccount\x12\x1b.users.UnlinkAccountRequest\x1a\x16.google.protobuf.Empty\x12H\n" +
 	"\x10GetLinkedAccount\x12\x1e.users.GetLinkedAccountRequest\x1a\x14.users.LinkedAccount\x12j\n" +
 	"\x1bGetLinkedAccountsByPlatform\x12).users.GetLinkedAccountsByPlatformRequest\x1a .users.GetLinkedAccountsResponse\x12x\n" +
-	"\"GetLinkedAccountsByUserAndPlatform\x120.users.GetLinkedAccountsByUserAndPlatformRequest\x1a .users.GetLinkedAccountsResponseB,Z*git.be.kaien.ru/l-ai/l-ai-core-proto/protob\x06proto3"
+	"\"GetLinkedAccountsByUserAndPlatform\x120.users.GetLinkedAccountsByUserAndPlatformRequest\x1a .users.GetLinkedAccountsResponse\x12_\n" +
+	"\x14ResolveLinkedAccount\x12\".users.ResolveLinkedAccountRequest\x1a#.users.ResolveLinkedAccountResponse\x12s\n" +
+	"\x1eResolveLinkedAccountByUsername\x12,.users.ResolveLinkedAccountByUsernameRequest\x1a#.users.ResolveLinkedAccountResponseB,Z*git.be.kaien.ru/l-ai/l-ai-core-proto/protob\x06proto3"
 
 var (
 	file_users_proto_rawDescOnce sync.Once
@@ -792,7 +971,7 @@ func file_users_proto_rawDescGZIP() []byte {
 	return file_users_proto_rawDescData
 }
 
-var file_users_proto_msgTypes = make([]protoimpl.MessageInfo, 12)
+var file_users_proto_msgTypes = make([]protoimpl.MessageInfo, 15)
 var file_users_proto_goTypes = []any{
 	(*GlobalUser)(nil),                                // 0: users.GlobalUser
 	(*LinkedAccount)(nil),                             // 1: users.LinkedAccount
@@ -806,37 +985,44 @@ var file_users_proto_goTypes = []any{
 	(*GetLinkedAccountsByPlatformRequest)(nil),        // 9: users.GetLinkedAccountsByPlatformRequest
 	(*GetLinkedAccountsByUserAndPlatformRequest)(nil), // 10: users.GetLinkedAccountsByUserAndPlatformRequest
 	(*GetLinkedAccountsResponse)(nil),                 // 11: users.GetLinkedAccountsResponse
-	(*timestamppb.Timestamp)(nil),                     // 12: google.protobuf.Timestamp
-	(*emptypb.Empty)(nil),                             // 13: google.protobuf.Empty
+	(*ResolveLinkedAccountRequest)(nil),               // 12: users.ResolveLinkedAccountRequest
+	(*ResolveLinkedAccountByUsernameRequest)(nil),     // 13: users.ResolveLinkedAccountByUsernameRequest
+	(*ResolveLinkedAccountResponse)(nil),              // 14: users.ResolveLinkedAccountResponse
+	(*timestamppb.Timestamp)(nil),                     // 15: google.protobuf.Timestamp
+	(*emptypb.Empty)(nil),                             // 16: google.protobuf.Empty
 }
 var file_users_proto_depIdxs = []int32{
-	12, // 0: users.GlobalUser.created_at:type_name -> google.protobuf.Timestamp
-	12, // 1: users.GlobalUser.updated_at:type_name -> google.protobuf.Timestamp
+	15, // 0: users.GlobalUser.created_at:type_name -> google.protobuf.Timestamp
+	15, // 1: users.GlobalUser.updated_at:type_name -> google.protobuf.Timestamp
 	1,  // 2: users.GlobalUser.linked_accounts:type_name -> users.LinkedAccount
-	12, // 3: users.LinkedAccount.linked_at:type_name -> google.protobuf.Timestamp
-	12, // 4: users.LinkedAccount.updated_at:type_name -> google.protobuf.Timestamp
+	15, // 3: users.LinkedAccount.linked_at:type_name -> google.protobuf.Timestamp
+	15, // 4: users.LinkedAccount.updated_at:type_name -> google.protobuf.Timestamp
 	0,  // 5: users.GetAllGlobalUsersResponse.users:type_name -> users.GlobalUser
 	1,  // 6: users.GetLinkedAccountsResponse.accounts:type_name -> users.LinkedAccount
 	2,  // 7: users.UsersService.CreateGlobalUser:input_type -> users.CreateGlobalUserRequest
 	3,  // 8: users.UsersService.GetGlobalUser:input_type -> users.GetGlobalUserRequest
-	13, // 9: users.UsersService.GetAllGlobalUsers:input_type -> google.protobuf.Empty
+	16, // 9: users.UsersService.GetAllGlobalUsers:input_type -> google.protobuf.Empty
 	5,  // 10: users.UsersService.UpdateDisplayName:input_type -> users.UpdateDisplayNameRequest
 	6,  // 11: users.UsersService.LinkAccount:input_type -> users.LinkAccountRequest
 	7,  // 12: users.UsersService.UnlinkAccount:input_type -> users.UnlinkAccountRequest
 	8,  // 13: users.UsersService.GetLinkedAccount:input_type -> users.GetLinkedAccountRequest
 	9,  // 14: users.UsersService.GetLinkedAccountsByPlatform:input_type -> users.GetLinkedAccountsByPlatformRequest
 	10, // 15: users.UsersService.GetLinkedAccountsByUserAndPlatform:input_type -> users.GetLinkedAccountsByUserAndPlatformRequest
-	0,  // 16: users.UsersService.CreateGlobalUser:output_type -> users.GlobalUser
-	0,  // 17: users.UsersService.GetGlobalUser:output_type -> users.GlobalUser
-	4,  // 18: users.UsersService.GetAllGlobalUsers:output_type -> users.GetAllGlobalUsersResponse
-	13, // 19: users.UsersService.UpdateDisplayName:output_type -> google.protobuf.Empty
-	1,  // 20: users.UsersService.LinkAccount:output_type -> users.LinkedAccount
-	13, // 21: users.UsersService.UnlinkAccount:output_type -> google.protobuf.Empty
-	1,  // 22: users.UsersService.GetLinkedAccount:output_type -> users.LinkedAccount
-	11, // 23: users.UsersService.GetLinkedAccountsByPlatform:output_type -> users.GetLinkedAccountsResponse
-	11, // 24: users.UsersService.GetLinkedAccountsByUserAndPlatform:output_type -> users.GetLinkedAccountsResponse
-	16, // [16:25] is the sub-list for method output_type
-	7,  // [7:16] is the sub-list for method input_type
+	12, // 16: users.UsersService.ResolveLinkedAccount:input_type -> users.ResolveLinkedAccountRequest
+	13, // 17: users.UsersService.ResolveLinkedAccountByUsername:input_type -> users.ResolveLinkedAccountByUsernameRequest
+	0,  // 18: users.UsersService.CreateGlobalUser:output_type -> users.GlobalUser
+	0,  // 19: users.UsersService.GetGlobalUser:output_type -> users.GlobalUser
+	4,  // 20: users.UsersService.GetAllGlobalUsers:output_type -> users.GetAllGlobalUsersResponse
+	16, // 21: users.UsersService.UpdateDisplayName:output_type -> google.protobuf.Empty
+	1,  // 22: users.UsersService.LinkAccount:output_type -> users.LinkedAccount
+	16, // 23: users.UsersService.UnlinkAccount:output_type -> google.protobuf.Empty
+	1,  // 24: users.UsersService.GetLinkedAccount:output_type -> users.LinkedAccount
+	11, // 25: users.UsersService.GetLinkedAccountsByPlatform:output_type -> users.GetLinkedAccountsResponse
+	11, // 26: users.UsersService.GetLinkedAccountsByUserAndPlatform:output_type -> users.GetLinkedAccountsResponse
+	14, // 27: users.UsersService.ResolveLinkedAccount:output_type -> users.ResolveLinkedAccountResponse
+	14, // 28: users.UsersService.ResolveLinkedAccountByUsername:output_type -> users.ResolveLinkedAccountResponse
+	18, // [18:29] is the sub-list for method output_type
+	7,  // [7:18] is the sub-list for method input_type
 	7,  // [7:7] is the sub-list for extension type_name
 	7,  // [7:7] is the sub-list for extension extendee
 	0,  // [0:7] is the sub-list for field type_name
@@ -853,7 +1039,7 @@ func file_users_proto_init() {
 			GoPackagePath: reflect.TypeOf(x{}).PkgPath(),
 			RawDescriptor: unsafe.Slice(unsafe.StringData(file_users_proto_rawDesc), len(file_users_proto_rawDesc)),
 			NumEnums:      0,
-			NumMessages:   12,
+			NumMessages:   15,
 			NumExtensions: 0,
 			NumServices:   1,
 		},

users.proto

@@ -19,6 +19,38 @@ service UsersService {
   rpc GetLinkedAccount(GetLinkedAccountRequest) returns (LinkedAccount);
   rpc GetLinkedAccountsByPlatform(GetLinkedAccountsByPlatformRequest) returns (GetLinkedAccountsResponse);
   rpc GetLinkedAccountsByUserAndPlatform(GetLinkedAccountsByUserAndPlatformRequest) returns (GetLinkedAccountsResponse);
+
+  // ResolveLinkedAccount resolves the global user owning a platform account
+  // (e.g. platform="telegram", account_id="<numeric Telegram user id>").
+  // This is a read-only, non-creating server-to-server identity lookup used
+  // by other services (e.g. l-ai-chat Telegram bridge) to map a transport
+  // identity to the stable global_user_id. It NEVER creates a global user or
+  // a linked account.
+  //
+  // Identity boundary invariant: (platform, account_id) -> at most one
+  // canonical global_user_id.
+  //   - no rows            -> linked=false (account not linked; nothing created)
+  //   - one distinct global user -> that user; if several legacy link rows
+  //     exist for the SAME user, the oldest (smallest linked_account id) wins,
+  //     deterministic across retries
+  //   - more than one distinct global user -> FAILS CLOSED with
+  //     FailedPrecondition (ambiguous identity); callers must not persist
+  //     anything under a guessed identity
+  rpc ResolveLinkedAccount(ResolveLinkedAccountRequest) returns (ResolveLinkedAccountResponse);
+
+  // ResolveLinkedAccountByUsername resolves the global user owning a platform
+  // account addressed by its username rather than its id (e.g.
+  // platform="telegram", username="kaien"). Read-only: it never creates a
+  // global user or a linked account.
+  //
+  // Callers that only know how a person is addressed in chat need this; the
+  // id-based lookup above cannot serve them. Same fail-closed identity rule:
+  //   - no match                    -> found=false
+  //   - one global user             -> that user
+  //   - more than one global user   -> FailedPrecondition (ambiguous), so a
+  //     caller never acts on a guessed identity. Acting on the wrong one here
+  //     can mean phoning a person who never asked to be called.
+  rpc ResolveLinkedAccountByUsername(ResolveLinkedAccountByUsernameRequest) returns (ResolveLinkedAccountResponse);
 }
 
 message GlobalUser {
@@ -88,3 +120,21 @@ message GetLinkedAccountsByUserAndPlatformRequest {
 message GetLinkedAccountsResponse {
   repeated LinkedAccount accounts = 1;
 }
+
+message ResolveLinkedAccountRequest {
+  string platform = 1;
+  string account_id = 2;
+}
+
+message ResolveLinkedAccountByUsernameRequest {
+  string platform = 1;
+  // Username without a leading "@"; matched case-insensitively, the way
+  // people write it in chat.
+  string username = 2;
+}
+
+message ResolveLinkedAccountResponse {
+  bool linked = 1;
+  int64 global_user_id = 2;
+  string display_name = 3;
+}

users_grpc.pb.go

@@ -1,7 +1,7 @@
 // Code generated by protoc-gen-go-grpc. DO NOT EDIT.
 // versions:
-// - protoc-gen-go-grpc v1.6.1
-// - protoc             v7.34.0
+// - protoc-gen-go-grpc v1.6.2
+// - protoc             (unknown)
 // source: users.proto
 
 package proto
@@ -29,6 +29,8 @@ const (
 	UsersService_GetLinkedAccount_FullMethodName                   = "/users.UsersService/GetLinkedAccount"
 	UsersService_GetLinkedAccountsByPlatform_FullMethodName        = "/users.UsersService/GetLinkedAccountsByPlatform"
 	UsersService_GetLinkedAccountsByUserAndPlatform_FullMethodName = "/users.UsersService/GetLinkedAccountsByUserAndPlatform"
+	UsersService_ResolveLinkedAccount_FullMethodName               = "/users.UsersService/ResolveLinkedAccount"
+	UsersService_ResolveLinkedAccountByUsername_FullMethodName     = "/users.UsersService/ResolveLinkedAccountByUsername"
 )
 
 // UsersServiceClient is the client API for UsersService service.
@@ -46,6 +48,36 @@ type UsersServiceClient interface {
 	GetLinkedAccount(ctx context.Context, in *GetLinkedAccountRequest, opts ...grpc.CallOption) (*LinkedAccount, error)
 	GetLinkedAccountsByPlatform(ctx context.Context, in *GetLinkedAccountsByPlatformRequest, opts ...grpc.CallOption) (*GetLinkedAccountsResponse, error)
 	GetLinkedAccountsByUserAndPlatform(ctx context.Context, in *GetLinkedAccountsByUserAndPlatformRequest, opts ...grpc.CallOption) (*GetLinkedAccountsResponse, error)
+	// ResolveLinkedAccount resolves the global user owning a platform account
+	// (e.g. platform="telegram", account_id="<numeric Telegram user id>").
+	// This is a read-only, non-creating server-to-server identity lookup used
+	// by other services (e.g. l-ai-chat Telegram bridge) to map a transport
+	// identity to the stable global_user_id. It NEVER creates a global user or
+	// a linked account.
+	//
+	// Identity boundary invariant: (platform, account_id) -> at most one
+	// canonical global_user_id.
+	//   - no rows            -> linked=false (account not linked; nothing created)
+	//   - one distinct global user -> that user; if several legacy link rows
+	//     exist for the SAME user, the oldest (smallest linked_account id) wins,
+	//     deterministic across retries
+	//   - more than one distinct global user -> FAILS CLOSED with
+	//     FailedPrecondition (ambiguous identity); callers must not persist
+	//     anything under a guessed identity
+	ResolveLinkedAccount(ctx context.Context, in *ResolveLinkedAccountRequest, opts ...grpc.CallOption) (*ResolveLinkedAccountResponse, error)
+	// ResolveLinkedAccountByUsername resolves the global user owning a platform
+	// account addressed by its username rather than its id (e.g.
+	// platform="telegram", username="kaien"). Read-only: it never creates a
+	// global user or a linked account.
+	//
+	// Callers that only know how a person is addressed in chat need this; the
+	// id-based lookup above cannot serve them. Same fail-closed identity rule:
+	//   - no match                    -> found=false
+	//   - one global user             -> that user
+	//   - more than one global user   -> FailedPrecondition (ambiguous), so a
+	//     caller never acts on a guessed identity. Acting on the wrong one here
+	//     can mean phoning a person who never asked to be called.
+	ResolveLinkedAccountByUsername(ctx context.Context, in *ResolveLinkedAccountByUsernameRequest, opts ...grpc.CallOption) (*ResolveLinkedAccountResponse, error)
 }
 
 type usersServiceClient struct {
@@ -146,6 +178,26 @@ func (c *usersServiceClient) GetLinkedAccountsByUserAndPlatform(ctx context.Cont
 	return out, nil
 }
 
+func (c *usersServiceClient) ResolveLinkedAccount(ctx context.Context, in *ResolveLinkedAccountRequest, opts ...grpc.CallOption) (*ResolveLinkedAccountResponse, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(ResolveLinkedAccountResponse)
+	err := c.cc.Invoke(ctx, UsersService_ResolveLinkedAccount_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
+func (c *usersServiceClient) ResolveLinkedAccountByUsername(ctx context.Context, in *ResolveLinkedAccountByUsernameRequest, opts ...grpc.CallOption) (*ResolveLinkedAccountResponse, error) {
+	cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)
+	out := new(ResolveLinkedAccountResponse)
+	err := c.cc.Invoke(ctx, UsersService_ResolveLinkedAccountByUsername_FullMethodName, in, out, cOpts...)
+	if err != nil {
+		return nil, err
+	}
+	return out, nil
+}
+
 // UsersServiceServer is the server API for UsersService service.
 // All implementations must embed UnimplementedUsersServiceServer
 // for forward compatibility.
@@ -161,6 +213,36 @@ type UsersServiceServer interface {
 	GetLinkedAccount(context.Context, *GetLinkedAccountRequest) (*LinkedAccount, error)
 	GetLinkedAccountsByPlatform(context.Context, *GetLinkedAccountsByPlatformRequest) (*GetLinkedAccountsResponse, error)
 	GetLinkedAccountsByUserAndPlatform(context.Context, *GetLinkedAccountsByUserAndPlatformRequest) (*GetLinkedAccountsResponse, error)
+	// ResolveLinkedAccount resolves the global user owning a platform account
+	// (e.g. platform="telegram", account_id="<numeric Telegram user id>").
+	// This is a read-only, non-creating server-to-server identity lookup used
+	// by other services (e.g. l-ai-chat Telegram bridge) to map a transport
+	// identity to the stable global_user_id. It NEVER creates a global user or
+	// a linked account.
+	//
+	// Identity boundary invariant: (platform, account_id) -> at most one
+	// canonical global_user_id.
+	//   - no rows            -> linked=false (account not linked; nothing created)
+	//   - one distinct global user -> that user; if several legacy link rows
+	//     exist for the SAME user, the oldest (smallest linked_account id) wins,
+	//     deterministic across retries
+	//   - more than one distinct global user -> FAILS CLOSED with
+	//     FailedPrecondition (ambiguous identity); callers must not persist
+	//     anything under a guessed identity
+	ResolveLinkedAccount(context.Context, *ResolveLinkedAccountRequest) (*ResolveLinkedAccountResponse, error)
+	// ResolveLinkedAccountByUsername resolves the global user owning a platform
+	// account addressed by its username rather than its id (e.g.
+	// platform="telegram", username="kaien"). Read-only: it never creates a
+	// global user or a linked account.
+	//
+	// Callers that only know how a person is addressed in chat need this; the
+	// id-based lookup above cannot serve them. Same fail-closed identity rule:
+	//   - no match                    -> found=false
+	//   - one global user             -> that user
+	//   - more than one global user   -> FailedPrecondition (ambiguous), so a
+	//     caller never acts on a guessed identity. Acting on the wrong one here
+	//     can mean phoning a person who never asked to be called.
+	ResolveLinkedAccountByUsername(context.Context, *ResolveLinkedAccountByUsernameRequest) (*ResolveLinkedAccountResponse, error)
 	mustEmbedUnimplementedUsersServiceServer()
 }
 
@@ -198,6 +280,12 @@ func (UnimplementedUsersServiceServer) GetLinkedAccountsByPlatform(context.Conte
 func (UnimplementedUsersServiceServer) GetLinkedAccountsByUserAndPlatform(context.Context, *GetLinkedAccountsByUserAndPlatformRequest) (*GetLinkedAccountsResponse, error) {
 	return nil, status.Error(codes.Unimplemented, "method GetLinkedAccountsByUserAndPlatform not implemented")
 }
+func (UnimplementedUsersServiceServer) ResolveLinkedAccount(context.Context, *ResolveLinkedAccountRequest) (*ResolveLinkedAccountResponse, error) {
+	return nil, status.Error(codes.Unimplemented, "method ResolveLinkedAccount not implemented")
+}
+func (UnimplementedUsersServiceServer) ResolveLinkedAccountByUsername(context.Context, *ResolveLinkedAccountByUsernameRequest) (*ResolveLinkedAccountResponse, error) {
+	return nil, status.Error(codes.Unimplemented, "method ResolveLinkedAccountByUsername not implemented")
+}
 func (UnimplementedUsersServiceServer) mustEmbedUnimplementedUsersServiceServer() {}
 func (UnimplementedUsersServiceServer) testEmbeddedByValue()                      {}
 
@@ -381,6 +469,42 @@ func _UsersService_GetLinkedAccountsByUserAndPlatform_Handler(srv interface{}, c
 	return interceptor(ctx, in, info, handler)
 }
 
+func _UsersService_ResolveLinkedAccount_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(ResolveLinkedAccountRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(UsersServiceServer).ResolveLinkedAccount(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: UsersService_ResolveLinkedAccount_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(UsersServiceServer).ResolveLinkedAccount(ctx, req.(*ResolveLinkedAccountRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _UsersService_ResolveLinkedAccountByUsername_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(ResolveLinkedAccountByUsernameRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(UsersServiceServer).ResolveLinkedAccountByUsername(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: UsersService_ResolveLinkedAccountByUsername_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(UsersServiceServer).ResolveLinkedAccountByUsername(ctx, req.(*ResolveLinkedAccountByUsernameRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
 // UsersService_ServiceDesc is the grpc.ServiceDesc for UsersService service.
 // It's only intended for direct use with grpc.RegisterService,
 // and not to be introspected or modified (even as a copy)
@@ -424,6 +548,14 @@ var UsersService_ServiceDesc = grpc.ServiceDesc{
 			MethodName: "GetLinkedAccountsByUserAndPlatform",
 			Handler:    _UsersService_GetLinkedAccountsByUserAndPlatform_Handler,
 		},
+		{
+			MethodName: "ResolveLinkedAccount",
+			Handler:    _UsersService_ResolveLinkedAccount_Handler,
+		},
+		{
+			MethodName: "ResolveLinkedAccountByUsername",
+			Handler:    _UsersService_ResolveLinkedAccountByUsername_Handler,
+		},
 	},
 	Streams:  []grpc.StreamDesc{},
 	Metadata: "users.proto",